From 235e1272c3fd60cf7d400ec3343e8a8f935aaa43 Mon Sep 17 00:00:00 2001
From: pranavkp71 <pranavkp170@gmail.com>
Date: Wed, 12 Nov 2025 12:26:28 +0530
Subject: [PATCH] DOC: Add documentation for pandas.api.typing.Expression
 (#63084)

---
 .../reference/api.typing.Expression.rst       | 33 +++++++++++++++++++
 doc/source/reference/index.rst                |  2 ++
 2 files changed, 35 insertions(+)
 create mode 100644 doc/source/reference/api.typing.Expression.rst

diff --git a/doc/source/reference/api.typing.Expression.rst b/doc/source/reference/api.typing.Expression.rst
new file mode 100644
index 0000000000000..66ea8d5daf6c2
--- /dev/null
+++ b/doc/source/reference/api.typing.Expression.rst
@@ -0,0 +1,33 @@
+pandas.API.typing.expression
+============================
+
+.. currentmodule:: pandas.api.typing
+
+.. autoclass:: Expression
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+**Description**
+
+An ``Expression`` represents a symbolic reference to a DataFrame column.
+It can be used inside functions like ``DataFrame.assign`` or ``DataFrame.loc`` to
+refer to columns in a declarative way.
+
+Example
+-------
+
+.. code-block:: python
+
+   import pandas as pd
+
+   df = pd.DataFrame({"a": [1, 2, 3]})
+   df.assign(b=pd.col("a") + 5)
+
+**Supported Operations**
+
+- Arithmetic: ``+``, ``-``, ``*``, ``/``
+- Comparison: ``<``, ``>``, ``==``, ``!=``
+- Universal functions (ufuncs): can be applied directly
+- Series accessors: ``.dt``, ``.str``, ``.cat``
+- Series methods: ``.sum()``, ``.mean()``, ``.astype()``, etc.
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index ec9e3c1bad476..979f2b1dd3ae5 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -56,6 +56,8 @@ to be stable.
    testing
    missing_value
    aliases
+   api.typing.Expression
+
 
 .. This is to prevent warnings in the doc build. We don't want to encourage
 .. these methods.