Skip to content
This repository has been archived by the owner on Nov 23, 2024. It is now read-only.

docs: remove type hints #125

Merged
merged 5 commits into from
Jan 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 27 additions & 50 deletions docs/development/project_guidelines.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
# Project Guidelines

This document describes general guidelines for the Safe-DS Python Library - Examples.
This document describes general guidelines for the Safe-DS Python Library Examples.

## Docstrings

The docstrings **should** use the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) format. The
descriptions **should not** start with "this" and **should** use imperative mood. Refer to the subsections below for
more details on how to document specific API elements.
descriptions **should not** start with "this" and **should** use imperative mood. Docstrings **should not** contain
type hints, since they are already specified in the code. Refer to the subsections below for more details on how to
document specific API elements.

!!! success "**DO**:"

Expand All @@ -32,39 +33,12 @@ more details on how to document specific API elements.
return a + b
```

!!! success "**DO**:"

```py
def __init__(self, data: Mapping[str, Any] | None = None) -> None:
"""
data : Mapping[str, Any] | None
"""
```

!!! failure "**DON'T**:"

```py
def __init__(self, data: Optional[Mapping[str, Any]] = None) -> None:
"""
data : Optional[Mapping[str, Any]]
"""
```

!!! failure "**DON'T**:"

```py
def __init__(self, data: Mapping[str, Any] | None = None) -> None:
"""
data : Optional[Mapping[str, Any]]
"""
```

### Modules

All modules should have

* a one-line description ([short summary][short-summary-section]),
* a longer description if needed ([extended summary][extended-summary-section]).
* A one-line description ([short summary][short-summary-section]).
* A longer description if needed ([extended summary][extended-summary-section]).

Example:

Expand All @@ -76,10 +50,11 @@ Example:

All classes should have

* a one-line description ([short summary][short-summary-section]),
* a longer description if needed ([extended summary][extended-summary-section])
* a description of the parameters of their `__init__` method ([`Parameters` section][parameters-section]),
* examples that show how to use them correctly ([`Examples` section][examples-section]).
* A one-line description ([short summary][short-summary-section]).
* A longer description if needed ([extended summary][extended-summary-section]).
* A description of the parameters of their `__init__` method ([`Parameters` section][parameters-section]). Omit types
and default values.
* Examples that show how to use them correctly ([`Examples` section][examples-section]).

Example:

Expand All @@ -89,7 +64,7 @@ A row is a collection of named values.

Parameters
----------
data : Mapping[str, Any] | None
data
The data. If None, an empty row is created.

Examples
Expand All @@ -103,15 +78,17 @@ Examples

All functions should have

* a one-line description ([short summary][short-summary-section]),
* a longer description if needed ([extended summary][extended-summary-section])
* a description of their parameters ([`Parameters` section][parameters-section]),
* a description of their results ([`Returns` section][returns-section]),
* a description of any exceptions that may be raised and under which conditions that may
happen ([`Raises` section][raises-section]),
* a description of any warnings that may be issued and under which conditions that may
happen ([`Warns` section][warns-section]),
* examples that show how to use them correctly ([`Examples` section][examples-section]).
* A one-line description ([short summary][short-summary-section]).
* A longer description if needed ([extended summary][extended-summary-section]).
* A description of their parameters ([`Parameters` section][parameters-section]). Omit types
and default values.
* A description of their results ([`Returns` section][returns-section]). Specify a name for the return value but omit
its type. Note that the colon after the name is required here, otherwise it will be interpreted as a type.
* A description of any exceptions that may be raised and under which conditions that may
happen ([`Raises` section][raises-section]).
* A description of any warnings that may be issued and under which conditions that may
happen ([`Warns` section][warns-section]).
* Examples that show how to use them correctly ([`Examples` section][examples-section]).

Example:

Expand All @@ -121,12 +98,12 @@ Return the value of a specified column.

Parameters
----------
column_name : str
column_name
The column name.

Returns
-------
value : Any
value :
The column value.

Raises
Expand Down Expand Up @@ -234,8 +211,8 @@ adding new classes to it.
]
```

[src-folder]: https://github.com/Safe-DS/Library/tree/main/src
[tests-folder]: https://github.com/Safe-DS/Library/tree/main/tests
[src-folder]: https://github.com/Safe-DS/Library-Examples/tree/main/src
[tests-folder]: https://github.com/Safe-DS/Library-Examples/tree/main/tests
[short-summary-section]: https://numpydoc.readthedocs.io/en/latest/format.html#short-summary
[extended-summary-section]: https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary
[parameters-section]: https://numpydoc.readthedocs.io/en/latest/format.html#parameters
Expand Down
13 changes: 8 additions & 5 deletions src/safeds_examples/tabular/_house_sales/_house_sales.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ def load_house_sales() -> ExampleTable:

Returns
-------
ExampleTable
house_sales :
The "House Sales" dataset.
"""
return ExampleTable(
Expand All @@ -32,15 +32,18 @@ def load_house_sales() -> ExampleTable:
"sqft_basement": "Interior living space below ground in square feet",
"floors": "Number of floors",
"bedrooms": "Number of bedrooms",
"bathrooms": "Number of bathrooms.\n\n"
"Fractional values indicate that components (toilet/sink/shower/bathtub) are missing.",
"bathrooms": (
"Number of bathrooms.\n\n"
"Fractional values indicate that components (toilet/sink/shower/bathtub) are missing."
),
"waterfront": "Whether the building overlooks a waterfront (0 = no, 1 = yes)",
"view": "Rating of the view (1 to 5, higher is better)",
"condition": "Rating of the condition of the house (1 to 5, higher is better)",
"grade": "Rating of building construction and design (1 to 13, higher is better)",
"year_built": "Year the house was built",
"year_renovated": "Year the house was last renovated.\n\n"
"A value of 0 indicates that it was never renovated.",
"year_renovated": (
"Year the house was last renovated.\n\nA value of 0 indicates that it was never renovated."
),
"sqft_lot_15nn": "Lot area of the 15 nearest neighbors in square feet",
"sqft_living_15nn": "Interior living space of the 15 nearest neighbors in square feet",
"price": "Price the house sold for in USD",
Expand Down
2 changes: 1 addition & 1 deletion src/safeds_examples/tabular/_titanic/_titanic.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ def load_titanic() -> ExampleTable:

Returns
-------
ExampleTable
titanic :
The "Titanic" dataset.
"""
return ExampleTable(
Expand Down
8 changes: 4 additions & 4 deletions src/safeds_examples/tabular/containers/_example_table.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ class ExampleTable(Table):

Parameters
----------
table : Table
table
The table.
column_descriptions : dict[str, str]
column_descriptions
A dictionary mapping column names to their descriptions.

Raises
Expand Down Expand Up @@ -50,12 +50,12 @@ def get_column_description(self, column_name: str) -> str:

Parameters
----------
column_name : str
column_name
The name of the column.

Returns
-------
description : str
column_description :
The description of the column.

Raises
Expand Down
Loading