Skip to content

Commit 964f3f2

Browse files
maxkrivachev-webmaxkrivachev-web
authored
docs: add mermaid diagrams
1 parent 39708b9 commit 964f3f2

File tree

1 file changed

+64
-112
lines changed

1 file changed

+64
-112
lines changed

‎README.md‎

Lines changed: 64 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,98 @@
1-
python-patterns
2-
===============
1+
# README.md — вставки с диаграммами Mermaid
32

4-
A collection of design patterns and idioms in Python.
3+
> Ниже показаны **три блока**, которые нужно вставить в `README.md` перед таблицей каждого раздела.
4+
> Каждый блок отделён от окружающего текста пустой строкой (требование GitHub Markdown renderer).
55
6-
Remember that each pattern has its own trade-offs. And you need to pay attention more to why you're choosing a certain pattern than to how to implement it.
6+
---
77

8-
Current Patterns
9-
----------------
8+
## 🔵 Вставка 1 — перед таблицей **Creational Patterns**
109

11-
__Creational Patterns__:
10+
Место: сразу после строки `## Creational Patterns` и перед строкой `| Pattern | Description |`
1211

13-
| Pattern | Description |
14-
|:-------:| ----------- |
15-
| [abstract_factory](patterns/creational/abstract_factory.py) | use a generic function with specific factories |
16-
| [borg](patterns/creational/borg.py) | a singleton with shared-state among instances |
17-
| [builder](patterns/creational/builder.py) | instead of using multiple constructors, builder object receives parameters and returns constructed objects |
18-
| [factory](patterns/creational/factory.py) | delegate a specialized function/method to create instances |
19-
| [lazy_evaluation](patterns/creational/lazy_evaluation.py) | lazily-evaluated property pattern in Python |
20-
| [pool](patterns/creational/pool.py) | preinstantiate and maintain a group of instances of the same type |
21-
| [prototype](patterns/creational/prototype.py) | use a factory and clones of a prototype for new instances (if instantiation is expensive) |
22-
23-
__Structural Patterns__:
12+
```markdown
13+
## Creational Patterns
2414

25-
| Pattern | Description |
26-
|:-------:| ----------- |
27-
| [3-tier](patterns/structural/3-tier.py) | data<->business logic<->presentation separation (strict relationships) |
28-
| [adapter](patterns/structural/adapter.py) | adapt one interface to another using a white-list |
29-
| [bridge](patterns/structural/bridge.py) | a client-provider middleman to soften interface changes |
30-
| [composite](patterns/structural/composite.py) | lets clients treat individual objects and compositions uniformly |
31-
| [decorator](patterns/structural/decorator.py) | wrap functionality with other functionality in order to affect outputs |
32-
| [facade](patterns/structural/facade.py) | use one class as an API to a number of others |
33-
| [flyweight](patterns/structural/flyweight.py) | transparently reuse existing instances of objects with similar/identical state |
34-
| [front_controller](patterns/structural/front_controller.py) | single handler requests coming to the application |
35-
| [mvc](patterns/structural/mvc.py) | model<->view<->controller (non-strict relationships) |
36-
| [proxy](patterns/structural/proxy.py) | an object funnels operations to something else |
37-
38-
__Behavioral Patterns__:
15+
> Patterns that deal with **object creation** — abstracting and controlling how instances are made.
3916
40-
| Pattern | Description |
41-
|:-------:| ----------- |
42-
| [chain_of_responsibility](patterns/behavioral/chain_of_responsibility.py) | apply a chain of successive handlers to try and process the data |
43-
| [catalog](patterns/behavioral/catalog.py) | general methods will call different specialized methods based on construction parameter |
44-
| [chaining_method](patterns/behavioral/chaining_method.py) | continue callback next object method |
45-
| [command](patterns/behavioral/command.py) | bundle a command and arguments to call later |
46-
| [iterator](patterns/behavioral/iterator.py) | traverse a container and access the container's elements |
47-
| [iterator](patterns/behavioral/iterator_alt.py) (alt. impl.)| traverse a container and access the container's elements |
48-
| [mediator](patterns/behavioral/mediator.py) | an object that knows how to connect other objects and act as a proxy |
49-
| [memento](patterns/behavioral/memento.py) | generate an opaque token that can be used to go back to a previous state |
50-
| [observer](patterns/behavioral/observer.py) | provide a callback for notification of events/changes to data |
51-
| [publish_subscribe](patterns/behavioral/publish_subscribe.py) | a source syndicates events/data to 0+ registered listeners |
52-
| [registry](patterns/behavioral/registry.py) | keep track of all subclasses of a given class |
53-
| [servant](patterns/behavioral/servant.py) | provide common functionality to a group of classes without using inheritance |
54-
| [specification](patterns/behavioral/specification.py) | business rules can be recombined by chaining the business rules together using boolean logic |
55-
| [state](patterns/behavioral/state.py) | logic is organized into a discrete number of potential states and the next state that can be transitioned to |
56-
| [strategy](patterns/behavioral/strategy.py) | selectable operations over the same data |
57-
| [template](patterns/behavioral/template.py) | an object imposes a structure but takes pluggable components |
58-
| [visitor](patterns/behavioral/visitor.py) | invoke a callback for all items of a collection |
59-
60-
__Design for Testability Patterns__:
17+
```mermaid
18+
graph LR
19+
Client -->|requests object| AbstractFactory
20+
AbstractFactory -->|delegates to| ConcreteFactory
21+
ConcreteFactory -->|produces| Product
6122
62-
| Pattern | Description |
63-
|:-------:| ----------- |
64-
| [dependency_injection](patterns/dependency_injection.py) | 3 variants of dependency injection |
23+
Builder -->|step-by-step| Director
24+
Director -->|returns| BuiltObject
6525
66-
__Fundamental Patterns__:
26+
FactoryMethod -->|subclass decides| ConcreteProduct
27+
Pool -->|reuses| PooledInstance
28+
```
6729

6830
| Pattern | Description |
69-
|:-------:| ----------- |
70-
| [delegation_pattern](patterns/fundamental/delegation_pattern.py) | an object handles a request by delegating to a second object (the delegate) |
31+
```
7132

72-
__Others__:
33+
---
7334

74-
| Pattern | Description |
75-
|:-------:| ----------- |
76-
| [blackboard](patterns/other/blackboard.py) | architectural model, assemble different sub-system knowledge to build a solution, AI approach - non gang of four pattern |
77-
| [graph_search](patterns/other/graph_search.py) | graphing algorithms - non gang of four pattern |
78-
| [hsm](patterns/other/hsm/hsm.py) | hierarchical state machine - non gang of four pattern |
35+
## 🟢 Вставка 2 — перед таблицей **Structural Patterns**
7936

37+
Место: сразу после строки `## Structural Patterns` и перед строкой `| Pattern | Description |`
8038

81-
Videos
82-
------
83-
[Design Patterns in Python by Peter Ullrich](https://www.youtube.com/watch?v=bsyjSW46TDg)
39+
```markdown
40+
## Structural Patterns
8441

85-
[Sebastian Buczyński - Why you don't need design patterns in Python?](https://www.youtube.com/watch?v=G5OeYHCJuv0)
42+
> Patterns that define **how classes and objects are composed** to form larger, flexible structures.
8643
87-
[You Don't Need That!](https://www.youtube.com/watch?v=imW-trt0i9I)
44+
```mermaid
45+
graph TD
46+
Client --> Facade
47+
Facade --> SubsystemA
48+
Facade --> SubsystemB
49+
Facade --> SubsystemC
8850
89-
[Pluggable Libs Through Design Patterns](https://www.youtube.com/watch?v=PfgEU3W0kyU)
51+
Client2 --> Adapter
52+
Adapter --> LegacyService
9053
54+
Client3 --> Proxy
55+
Proxy -->|controls access to| RealSubject
9156
92-
Contributing
93-
------------
94-
When an implementation is added or modified, please review the following guidelines:
57+
Component --> Composite
58+
Composite --> Leaf1
59+
Composite --> Leaf2
60+
```
9561

96-
##### Docstrings
97-
Add module level description in form of a docstring with links to corresponding references or other useful information.
98-
99-
Add "Examples in Python ecosystem" section if you know some. It shows how patterns could be applied to real-world problems.
100-
101-
[facade.py](patterns/structural/facade.py) has a good example of detailed description,
102-
but sometimes the shorter one as in [template.py](patterns/behavioral/template.py) would suffice.
103-
104-
##### Python 2 compatibility
105-
To see Python 2 compatible versions of some patterns please check-out the [legacy](https://github.com/faif/python-patterns/tree/legacy) tag.
62+
| Pattern | Description |
63+
```
10664

107-
##### Update README
108-
When everything else is done - update corresponding part of README.
65+
---
10966

110-
##### Travis CI
111-
Please run the following before submitting a patch
112-
- `black .` This lints your code.
67+
## 🟠 Вставка 3 — перед таблицей **Behavioral Patterns**
11368

114-
Then either:
115-
- `tox` or `tox -e ci37` This runs unit tests. see tox.ini for further details.
116-
- If you have a bash compatible shell use `./lint.sh` This script will lint and test your code. This script mirrors the CI pipeline actions.
69+
Место: сразу после строки `## Behavioral Patterns` и перед строкой `| Pattern | Description |`
11770

118-
You can also run `flake8` or `pytest` commands manually. Examples can be found in `tox.ini`.
71+
```markdown
72+
## Behavioral Patterns
11973

120-
## Contributing via issue triage [![Open Source Helpers](https://www.codetriage.com/faif/python-patterns/badges/users.svg)](https://www.codetriage.com/faif/python-patterns)
74+
> Patterns concerned with **communication and responsibility** between objects.
12175
122-
You can triage issues and pull requests which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to python-patterns on CodeTriage](https://www.codetriage.com/faif/python-patterns).
76+
```mermaid
77+
graph LR
78+
Sender -->|sends event| Observer1
79+
Sender -->|sends event| Observer2
12380
81+
Request --> Handler1
82+
Handler1 -->|passes if unhandled| Handler2
83+
Handler2 -->|passes if unhandled| Handler3
12484
125-
## 🚫 Anti-Patterns
85+
Context -->|delegates to| Strategy
86+
Strategy -->|executes| Algorithm
12687
127-
This section lists some common design patterns that are **not recommended** in Python and explains why.
88+
Originator -->|saves state to| Memento
89+
Caretaker -->|holds| Memento
90+
```
12891

129-
### 🧱 Singleton
130-
**Why not:**
131-
- Python modules are already singletons — every module is imported only once.
132-
- Explicit singleton classes add unnecessary complexity.
133-
- Better alternatives: use module-level variables or dependency injection.
92+
| Pattern | Description |
93+
```
13494

135-
### 🌀 God Object
136-
**Why not:**
137-
- Centralizes too much logic in a single class.
138-
- Makes code harder to test and maintain.
139-
- Better alternative: split functionality into smaller, cohesive classes.
95+
---
14096

141-
### 🔁 Inheritance overuse
142-
**Why not:**
143-
- Deep inheritance trees make code brittle.
144-
- Prefer composition and delegation.
145-
- “Favor composition over inheritance.”
97+
> **Примечание для ревьюеров:** диаграммы намеренно упрощены — цель показать *ключевое взаимодействие* каждой группы, а не полную UML-схему каждого паттерна. Детали реализации — в `.py`-файлах.
14698

0 commit comments

Comments
 (0)