From 4a785b377e528ccad330db88b94f10cce78006f3 Mon Sep 17 00:00:00 2001 From: somespecialone Date: Tue, 1 Oct 2024 16:07:39 +0200 Subject: [PATCH] Enum's explanation --- README.md | 1 + docs/design.md | 20 +++++++++++++++----- docs/enums.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 68 insertions(+), 5 deletions(-) create mode 100644 docs/enums.md diff --git a/README.md b/README.md index 8506bed..94ca06f 100644 --- a/README.md +++ b/README.md @@ -166,5 +166,6 @@ I will be very grateful for helping me get the things right. - [Steam Market id's storage repo](https://github.com/somespecialone/steam-item-name-ids) - [steamapi.xpaw.me](https://steamapi.xpaw.me/) - [Steam Exchange Rate Tracker](https://github.com/somespecialone/sert) +- [ethanfurman/aenum](https://github.com/ethanfurman/aenum) diff --git a/docs/design.md b/docs/design.md index 1970009..e9e5b5d 100644 --- a/docs/design.md +++ b/docs/design.md @@ -8,7 +8,7 @@ Designed to be flexible with modest complexity, while being typed and developer As you can read in [previous](./get_started.md#first-words) chapter, there is two **clients**: public and non-public. Both represents interaction layer with `SteamCommunity`. Each **client** instance has separate `session`, therefore as **cookies**, and other properties -(country, currency, ...). +(country, currency, ...). !!! tip Think of them as a private-mode window of a web browser. Each **client** instance is a new private mode window, @@ -46,20 +46,30 @@ This classes inherit all corresponding mixins. [Inheritance](./client.md#inherit There is two general types of exceptions: `python` (builtin exceptions, related to invalid arguments values, broken connection, so on) and `steam`, that raised when code faced error while trying to interact with `Steam`, as follows: `Steam` cannot return market listings, items not in inventory, malformed response, `Steam` -return error result (`EResult`) deliberately for some reason (lol) or even give your **client** (mainly, by ip) a -rate limit restriction ([more information](./scraping.md)). +return error result (`EResult`) deliberately for some reason (😂) or even give your **client** (mainly, by ip) a +[rate limit restriction](./scraping.md). ### Modules & entrypoints `Aiosteampy` contains `utils` and `helpers` moduls, each contain useful utilities to make work with **client** easier. -[There is](./utils_helpers.md) +[Is there](./utils_helpers.md) Alongside with mentioned moduls project have a few `extensions`: - [user agents](./ext/user_agents.md) - service, which main aim is to help get random user agent for your **client/s** - [currency converter](./ext/converter.md) - service, aims to help you convert `Steam` currencies +### Enums + +At last, within the project exists two special enums `App` and `AppContext` with unusual behaviour (for `python`). +In short, _they extend itself when member is missing_, previous means that hardcoded members are just _predefined_. + +!!! warning "" + Generally, `aiosteampy` support all apps and contexts! + +More on [dedicated page](./enums.md), worth reading. + ## Epilogue _That's it_. Further information introduce short overview of methods, how things work more detailed and even -hard to say some patterns. Good luck 👋! +hard to say some patterns. Good luck 👋 diff --git a/docs/enums.md b/docs/enums.md new file mode 100644 index 0000000..9180e17 --- /dev/null +++ b/docs/enums.md @@ -0,0 +1,51 @@ +Let's talk about `App` and `AppContext` enum's a little. + +Thankfully to an [aenum](https://github.com/ethanfurman/aenum) package, these enum's extending selves when member is +missing. Therefore, as mentioned before, hardcoded members are just _predefined_. + +!!! note "" + You can create `App` and `AppContext` for non-predefined app+context + +As instance: + +```python +from aiosteampy import App, AppContext + +BANANA_APP = App(2923300) +BANANA = AppContext((BANANA_APP, 2)) # with context 2 +``` + +And then use it within your app. Moreover, from now `AppContext` and `App` enums have a new member. + +### Caveat + +If you print/log `BANANA_APP` you receive something like + +```sh +, 2)> +``` + +Not so beautiful, yes. Name is auto-generated, due to inability to know name of the app, if we, for example, +get a `trade offer` with non-predefined app items. + +!!! warning "Next version" + Solution comes in next minor version (0.6.4) + +As a workaround you can extend enum manually: + +```python +from aenum import extend_enum +from aiosteampy import App, AppContext + +BANANA_APP = extend_enum(App, "BANANA", 2923300) +BANANA_DEFAULT_CONTEXT = extend_enum( + AppContext, + "BANANA_DEFAULT_CONTEXT", + (BANANA_APP, 2), +) # with context 2 +``` + +Then `repr` of a `AppContext` new member will be: +```sh +, 2)> +``` diff --git a/mkdocs.yml b/mkdocs.yml index b144ad7..cf20ece 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,7 @@ nav: - "Proxies 🌐": proxies.md - Session: session.md - "Scraping 🕷️": scraping.md + - Enums: enums.md - Client: client.md - "Market 💹": market.md - Trade: trade.md