From 6d5126a9b1b5e77b4c5bac7a07fded25d9e13d6f Mon Sep 17 00:00:00 2001 From: bleudev Date: Sat, 1 Jun 2024 21:55:11 +0300 Subject: [PATCH 1/7] Create CONTRIBUTING.md --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d343f4d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# 📖 Contributing rules in `ufpy` repository + +If you want to contribute, you have to read this rules and follow they. From b8a5a216efc39074eeb0815f6634b906c61a718c Mon Sep 17 00:00:00 2001 From: bleudev Date: Sat, 1 Jun 2024 22:53:14 +0300 Subject: [PATCH 2/7] Code style --- CONTRIBUTING.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d343f4d..5828561 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,42 @@ # 📖 Contributing rules in `ufpy` repository If you want to contribute, you have to read this rules and follow they. + +## 💻 Code style + +- Formatter: `black` +- Optimizer of imports: `isort` +- Linter: `Pylint` +- Generic style: `True` + +Generic style is style where are using `typing.Generic` class in all `useful classes` + +For example, +```python +from typing import Generic, TypeVar + +T = TypeVar('T') + +class A(Generic[T]): + def __init__(self, a: T): ... +``` + +- `@overload`s: `True` + +You must define `@typing.overload`s in public methods when your method has two and more ways to define arguments +For example, +```python +@overload +def a(x: int): ... +@overload +def a(x: list): ... +@overload +def a(x: dict): ... +def a(x: int | list | dict): ... +``` + +- `__all__` variable: `True` + +`__all__` variable is variable with names of every class, +function and variable in module which needs to import. +When you use `from x import *` syntax, you import all names from `x.__all__` variable. From 42dfdf0caec2e3365a2cf4278df9c608a74b7626 Mon Sep 17 00:00:00 2001 From: bleudev Date: Sun, 2 Jun 2024 15:50:10 +0300 Subject: [PATCH 3/7] Fix things from review --- CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5828561..a0f6829 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # 📖 Contributing rules in `ufpy` repository -If you want to contribute, you have to read this rules and follow they. +If you want to contribute the project, you must read this rules and follow they. ## 💻 Code style @@ -9,7 +9,7 @@ If you want to contribute, you have to read this rules and follow they. - Linter: `Pylint` - Generic style: `True` -Generic style is style where are using `typing.Generic` class in all `useful classes` +Use `typing.Generic`s in your useful classes. For example, ```python @@ -23,7 +23,8 @@ class A(Generic[T]): - `@overload`s: `True` -You must define `@typing.overload`s in public methods when your method has two and more ways to define arguments +Use decorator `@typing.overload` in public methods if your method +has two and more variants to define arguments For example, ```python @overload From e824d2ee03afe64f827310fd9d4e4a97c6ca3f97 Mon Sep 17 00:00:00 2001 From: bleudev Date: Mon, 3 Jun 2024 21:36:38 +0300 Subject: [PATCH 4/7] Final `code style` --- CONTRIBUTING.md | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0f6829..f5af126 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ If you want to contribute the project, you must read this rules and follow they. - Formatter: `black` - Optimizer of imports: `isort` - Linter: `Pylint` -- Generic style: `True` +- `Generic` Use `typing.Generic`s in your useful classes. @@ -21,7 +21,7 @@ class A(Generic[T]): def __init__(self, a: T): ... ``` -- `@overload`s: `True` +- `@overload`s Use decorator `@typing.overload` in public methods if your method has two and more variants to define arguments @@ -36,8 +36,43 @@ def a(x: dict): ... def a(x: int | list | dict): ... ``` -- `__all__` variable: `True` +- `__all__` `__all__` variable is variable with names of every class, function and variable in module which needs to import. When you use `from x import *` syntax, you import all names from `x.__all__` variable. +Example: +```python +__all__ = ( + 'abc', + 'Abc', +) + +def abc(): ... +class Abc: ... +``` + +- `__future__.annotations` + +If you use your class in annotations in method's signatures of this, you should import +`__future__.annotations`. Don't use string annotations! + +```python +# don't this +class A: + def a(self, b: 'A') -> 'A': ... + +# do this +from __future__ import annotations + +class A: + def a(self, b: A) -> A: ... +``` + +## ✅ Tests rules + +... + +## 📺 Examples rules + +... From 364685c5df1d5ff1936313c5347a7fe224fc15cd Mon Sep 17 00:00:00 2001 From: bleudev Date: Tue, 4 Jun 2024 17:08:39 +0300 Subject: [PATCH 5/7] Tests in CONTRIBUTING.md --- CONTRIBUTING.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5af126..6ef557b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,7 +71,25 @@ class A: ## ✅ Tests rules -... +When you create new class for library you should add tests. All tests must be Unittests and +contains all public features of class. +[How to write unittest?](https://realpython.com/python-testing/#how-to-structure-a-simple-test) + +Example of test for UDict class: +```python +import unittest + +from ufpy import UDict + + +class UDictTestCase(unittest.TestCase): + def test_init(self): + d = UDict(hello=1, hi=2, default=10) + d2 = UDict({'hello': 1, 'hi': 2}) + self.assertEqual(d.default, 10) + self.assertDictEqual(d.dictionary, d2.dictionary) + self.assertEqual(d, d2) +``` ## 📺 Examples rules From e4d4f0f92875c764bf8e8fcc6b5d9fda201f36f7 Mon Sep 17 00:00:00 2001 From: bleudev Date: Tue, 4 Jun 2024 17:31:58 +0300 Subject: [PATCH 6/7] Final examples --- CONTRIBUTING.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 69 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ef557b..c8b4f90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,8 +71,8 @@ class A: ## ✅ Tests rules -When you create new class for library you should add tests. All tests must be Unittests and -contains all public features of class. +When you create new class for library you should add tests. All tests must be Unittests, +be in `tests` directory and contains all public features of class. [How to write unittest?](https://realpython.com/python-testing/#how-to-structure-a-simple-test) Example of test for UDict class: @@ -93,4 +93,70 @@ class UDictTestCase(unittest.TestCase): ## 📺 Examples rules -... +When you create new class for library you also should add examples. All examples must be +`markdown` files, be in `examples` directory and contains all general public features of class. + +Example of example: +```markdown + # UDict + + ## Introduction + + UDict is class which is simplifying working with Python dicts. + It has many methods, properties, magic methods. + + Firstly, import `UDict` from `ufpy` + ```python + from ufpy import UDict + ``` + + ## Create UDict + + For creating UDict you should use this code: + ```python + d = UDict({'id': 2, 'content': 'hello, world'}) + # for string keys you can use this way: + d = UDict(id=2, content='hello, world') + ``` + + You can also define `default` value for items when you use item's getter: + ```python + d = UDict(id=2, content='hello, world', default=0) + ``` + + ## Get items + + For getting items you should use the way you use in lists and dicts: + use `UDict[key]` syntax: + ```python + d['id'] # 2 + ``` +``` + +### Cautions and notes + +Also, you can use cautions and notes in your examples. + +#### Caution + +Code: +```markdown +> [!CAUTION] +> This is caution! +``` + +How it's looking: +> [!CAUTION] +> This is caution! + +#### Note + +Code: +```markdown +> [!NOTE] +> This is caution! +``` + +How it's looking: +> [!NOTE] +> This is caution! From 16d708158450902830ab90e02adf5a00f13b221c Mon Sep 17 00:00:00 2001 From: bleudev Date: Wed, 5 Jun 2024 00:34:07 +0300 Subject: [PATCH 7/7] Fix `caution` -> `note` --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8b4f90..98718c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,9 +154,9 @@ How it's looking: Code: ```markdown > [!NOTE] -> This is caution! +> This is note! ``` How it's looking: > [!NOTE] -> This is caution! +> This is note!