From a304ad9a84ae5d35e378455d4e14ec84206e396c Mon Sep 17 00:00:00 2001 From: reyan-singh Date: Thu, 27 Mar 2025 10:00:46 +0530 Subject: [PATCH 1/2] Adding Type Aliases Documentation Adding documentation for Type Aliases - issue # 84 --- docs/general/user-guide/5_type_aliases.md | 92 +++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/general/user-guide/5_type_aliases.md diff --git a/docs/general/user-guide/5_type_aliases.md b/docs/general/user-guide/5_type_aliases.md new file mode 100644 index 00000000..32585fef --- /dev/null +++ b/docs/general/user-guide/5_type_aliases.md @@ -0,0 +1,92 @@ +# 📌 Type Aliases Documentation + +## What are Type Aliases? +A **type alias** assigns a meaningful name to an existing type. It helps improve **code readability** and **maintainability**, especially when dealing with **complex types**. + +### **Example:** +```python +GridCapacity = PandasGridCapacity | PolarsGridCapacity +``` +Here, `GridCapacity` is a shorthand for both Pandas and Polars grid capacities. + +--- + +## **📂 Type Aliases by File** + +### **📁 types_.py** *(Core Type Aliases)* + +#### **🔹 Agnostic Types** +- `AgnosticMask` → Flexible type for masks (`Any | Sequence[Any] | None`) +- `AgnosticAgentMask` → Selection filters for agents (`Sequence[int] | int | Literal["all", "active"] | None`) +- `AgnosticIds` → Unique agent IDs (`int | Collection[int]`) + +#### **🔹 Pandas Types** +- `PandasMask` → Mask type for Pandas (`pd.Series | pd.DataFrame | AgnosticMask`) +- `AgentPandasMask` → Agent-specific mask for Pandas (`AgnosticAgentMask | pd.Series | pd.DataFrame`) +- `PandasIdsLike` → ID representations in Pandas (`AgnosticIds | pd.Series | pd.Index`) +- `PandasGridCapacity` → Grid capacity stored in a NumPy array (`ndarray`) + +#### **🔹 Polars Types** +- `PolarsMask` → Mask type for Polars (`pl.Expr | pl.Series | pl.DataFrame | AgnosticMask`) +- `AgentPolarsMask` → Agent-specific mask for Polars (`AgnosticAgentMask | pl.Expr | pl.Series | pl.DataFrame | Sequence[int]`) +- `PolarsIdsLike` → ID representations in Polars (`AgnosticIds | pl.Series`) +- `PolarsGridCapacity` → Grid capacity using Polars expressions (`list[pl.Expr]`) + +#### **🔹 Generic Types** +- `DataFrame` → Supports Pandas & Polars DataFrames (`pd.DataFrame | pl.DataFrame`) +- `DataFrameInput` → Accepted DataFrame inputs (`dict[str, Any] | Sequence[Sequence] | DataFrame`) +- `Series` → Pandas or Polars Series (`pd.Series | pl.Series`) +- `Index` → Indexing type (`pd.Index | pl.Series`) +- `BoolSeries` → Boolean Series representation (`pd.Series | pl.Series`) +- `Mask` → General mask type (`PandasMask | PolarsMask`) +- `AgentMask` → General agent mask (`AgentPandasMask | AgentPolarsMask`) +- `IdsLike` → ID representations (`AgnosticIds | PandasIdsLike | PolarsIdsLike`) +- `ArrayLike` → Array representation (`ndarray | Series | Sequence`) + +#### **🔹 Time-Related Types** +- `TimeT` → Time-based values (`float | int`) + +#### **🔹 Space Types** +- `NetworkCoordinate` → Network-based coordinate (`int | DataFrame`) +- `GridCoordinate` → Grid-based coordinate (`int | Sequence[int] | DataFrame`) +- `DiscreteCoordinate` → Discrete spatial coordinate (`NetworkCoordinate | GridCoordinate`) +- `ContinousCoordinate` → Continuous spatial coordinate (`float | Sequence[float] | DataFrame`) +- `SpaceCoordinate` → General space coordinate (`DiscreteCoordinate | ContinousCoordinate`) + +- `GridCapacity` → Grid storage capacity (`PandasGridCapacity | PolarsGridCapacity`) +- `NetworkCapacity` → Network storage capacity (`DataFrame`) +- `DiscreteSpaceCapacity` → Discrete space capacity alias (`GridCapacity | NetworkCapacity`) + +--- + +### **📁 space.py** +- `ESPG` → Defines an integer alias for EPSG codes in spatial reference systems (`int`) + +--- + +### **📁 agents.py** + +#### **🔹 Agent Identifiers & Storage** +- `IdsLike` → `AgnosticIds | PandasIdsLike | PolarsIdsLike`Used for identifying agents in collections +- `AgentMask` → `AgentPandasMask | AgentPolarsMask`Used for filtering/selecting agents + +#### **🔹 Agent Data Representation** +- `BoolSeries` → `pd.Series | pl.Series`Boolean representation of agents +- `Series` → `pd.Series | pl.Series`Holds a Pandas or Polars Series for agent data +- `DataFrameInput` → `dict[str, Any] | Sequence[Sequence] | DataFrame`Accepted input formats for DataFrames + +--- + + +### **📁 mixin.py** + +#### **🔹 Utility Type Aliases** +- `BoolSeries` → `pd.Series | pl.Series` Used for boolean operations in mixins +- `DataFrame` → `pd.DataFrame | pl.DataFrame`Used in mixins for defining DataFrame operations +- `Index` → `pd.Index | pl.Series`Used for indexing operations in mixins +- `Mask` → `PandasMask | PolarsMask`General mask type +- `Series` → `pd.Series | pl.Series` Pandas or Polars series representation + +--- + + From 0983f0532c1c7d08ba66aed2663f777f6af8679b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 27 Mar 2025 04:32:01 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/general/user-guide/5_type_aliases.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/general/user-guide/5_type_aliases.md b/docs/general/user-guide/5_type_aliases.md index 32585fef..564944ca 100644 --- a/docs/general/user-guide/5_type_aliases.md +++ b/docs/general/user-guide/5_type_aliases.md @@ -1,12 +1,15 @@ # 📌 Type Aliases Documentation -## What are Type Aliases? +## What are Type Aliases? + A **type alias** assigns a meaningful name to an existing type. It helps improve **code readability** and **maintainability**, especially when dealing with **complex types**. ### **Example:** + ```python GridCapacity = PandasGridCapacity | PolarsGridCapacity ``` + Here, `GridCapacity` is a shorthand for both Pandas and Polars grid capacities. --- @@ -16,23 +19,27 @@ Here, `GridCapacity` is a shorthand for both Pandas and Polars grid capacities. ### **📁 types_.py** *(Core Type Aliases)* #### **🔹 Agnostic Types** + - `AgnosticMask` → Flexible type for masks (`Any | Sequence[Any] | None`) - `AgnosticAgentMask` → Selection filters for agents (`Sequence[int] | int | Literal["all", "active"] | None`) - `AgnosticIds` → Unique agent IDs (`int | Collection[int]`) #### **🔹 Pandas Types** + - `PandasMask` → Mask type for Pandas (`pd.Series | pd.DataFrame | AgnosticMask`) - `AgentPandasMask` → Agent-specific mask for Pandas (`AgnosticAgentMask | pd.Series | pd.DataFrame`) - `PandasIdsLike` → ID representations in Pandas (`AgnosticIds | pd.Series | pd.Index`) - `PandasGridCapacity` → Grid capacity stored in a NumPy array (`ndarray`) #### **🔹 Polars Types** + - `PolarsMask` → Mask type for Polars (`pl.Expr | pl.Series | pl.DataFrame | AgnosticMask`) - `AgentPolarsMask` → Agent-specific mask for Polars (`AgnosticAgentMask | pl.Expr | pl.Series | pl.DataFrame | Sequence[int]`) - `PolarsIdsLike` → ID representations in Polars (`AgnosticIds | pl.Series`) - `PolarsGridCapacity` → Grid capacity using Polars expressions (`list[pl.Expr]`) #### **🔹 Generic Types** + - `DataFrame` → Supports Pandas & Polars DataFrames (`pd.DataFrame | pl.DataFrame`) - `DataFrameInput` → Accepted DataFrame inputs (`dict[str, Any] | Sequence[Sequence] | DataFrame`) - `Series` → Pandas or Polars Series (`pd.Series | pl.Series`) @@ -44,9 +51,11 @@ Here, `GridCapacity` is a shorthand for both Pandas and Polars grid capacities. - `ArrayLike` → Array representation (`ndarray | Series | Sequence`) #### **🔹 Time-Related Types** + - `TimeT` → Time-based values (`float | int`) #### **🔹 Space Types** + - `NetworkCoordinate` → Network-based coordinate (`int | DataFrame`) - `GridCoordinate` → Grid-based coordinate (`int | Sequence[int] | DataFrame`) - `DiscreteCoordinate` → Discrete spatial coordinate (`NetworkCoordinate | GridCoordinate`) @@ -60,27 +69,30 @@ Here, `GridCapacity` is a shorthand for both Pandas and Polars grid capacities. --- ### **📁 space.py** + - `ESPG` → Defines an integer alias for EPSG codes in spatial reference systems (`int`) --- -### **📁 agents.py** +### **📁 agents.py** #### **🔹 Agent Identifiers & Storage** + - `IdsLike` → `AgnosticIds | PandasIdsLike | PolarsIdsLike`Used for identifying agents in collections - `AgentMask` → `AgentPandasMask | AgentPolarsMask`Used for filtering/selecting agents #### **🔹 Agent Data Representation** + - `BoolSeries` → `pd.Series | pl.Series`Boolean representation of agents - `Series` → `pd.Series | pl.Series`Holds a Pandas or Polars Series for agent data - `DataFrameInput` → `dict[str, Any] | Sequence[Sequence] | DataFrame`Accepted input formats for DataFrames --- - -### **📁 mixin.py** +### **📁 mixin.py** #### **🔹 Utility Type Aliases** + - `BoolSeries` → `pd.Series | pl.Series` Used for boolean operations in mixins - `DataFrame` → `pd.DataFrame | pl.DataFrame`Used in mixins for defining DataFrame operations - `Index` → `pd.Index | pl.Series`Used for indexing operations in mixins @@ -88,5 +100,3 @@ Here, `GridCapacity` is a shorthand for both Pandas and Polars grid capacities. - `Series` → `pd.Series | pl.Series` Pandas or Polars series representation --- - -