From a997d6dd85b0fbe320cafc8988295bb7090ebe53 Mon Sep 17 00:00:00 2001 From: bleudev <95937737+bleudev@users.noreply.github.com> Date: Fri, 5 Jul 2024 18:50:46 +0300 Subject: [PATCH] `UDict` docs (#7) This pull request updates the documentation for the `UDict` class, introduces the new `uSTL` package with initial documentation for the `Stack` class, and deprecates the `UStack` class. It also enhances the MkDocs theme configuration and simplifies the CI workflow for documentation deployment. - **New Features**: - Introduced `uSTL` package with initial documentation for `Stack` class. - **Enhancements**: - Updated `UDict` documentation to improve clarity and consistency, including better formatting and additional examples. - Added a logo to the MkDocs theme configuration. - Enhanced MkDocs theme with new features like content code annotation and updated navigation settings. - **CI**: - Simplified the GitHub Actions workflow for deploying MkDocs by removing specific branch restrictions. - **Documentation**: - Deprecated `UStack` class in favor of `uSTL.Stack` and updated its documentation accordingly. - Updated the main index documentation to reflect the new structure and features, including the `uSTL` package and its components. --- .github/workflows/deploy_mkdocs.yml | 7 +- docs/assets/images/favicon.png | Bin 0 -> 3740 bytes docs/assets/images/logo.png | Bin 0 -> 5610 bytes docs/index.md | 9 +- docs/uSTL/index.md | 7 + docs/uSTL/stack.md | 8 + docs/useful_classes/udict.md | 375 +++++++++++++++++++---- docs/useful_classes/ustack.md | 8 +- docs/{ => useful_features}/generators.md | 0 mkdocs.yml | 9 +- 10 files changed, 357 insertions(+), 66 deletions(-) create mode 100644 docs/assets/images/favicon.png create mode 100644 docs/assets/images/logo.png create mode 100644 docs/uSTL/index.md create mode 100644 docs/uSTL/stack.md rename docs/{ => useful_features}/generators.md (100%) diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml index c888c19..4460b52 100644 --- a/.github/workflows/deploy_mkdocs.yml +++ b/.github/workflows/deploy_mkdocs.yml @@ -1,11 +1,10 @@ name: deploy_mkdocs on: - push: - branches: - - master - - main + push + permissions: contents: write + jobs: deploy: runs-on: ubuntu-latest diff --git a/docs/assets/images/favicon.png b/docs/assets/images/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..04e60247b910e21062581e006d69e82393d853af GIT binary patch literal 3740 zcmeHK`B#%y8opl$ge^p+EXrn;f(nEnP@sSb2!o6$Xq7Dnf`~yN5m6MeQWOlz3ivk zu8(lqphCFASn(hGkhTh2o|VjXBhNo0ILh{9&+M#aYo)!VeIF%q{c=G}VRv*Yyt5&B z)nWCHY_k8!Qm$PVlB|D5HDfTtF05sdA|7u&^#Ch0^jJ8TW57LeUR^L_)%nr!;CXsX zR%)^)DAI)hkXHg=-w^;vPO?K&-T{EucL2btXaGJl1fXd5pCM%!YLkq{DE>Fo`(;Fh z51{x~i02UM|AVEORq%W;E$EQay+)mjuK(J;;i)~~Vu$9RSL8pF&L0%ATUVfDXBmI2 zTL9Lol)Z5ORvxmVkEWhOfhWcQ{zVD)ZvZ4T;Bs^z?fc;AV-?^6P6d}GJZJznJwX4P zbi4N`!a>NZGcV|(z5*46D$*na;X4}2!&&B4`;wBQZUPWPG|4fKV9Zo)@5jV{4tZr- zb|)+gfssW!h}XQ`kq!%gY0FY2Y=^vhjPMS5Dl}>P6dPUoIS7m9-_NLRwb;a`ge$_i zy72;zJp706?H(joKm8~AS*dgg4bBALhI%uC!v{gc%kPiBtVq)0KNd8gWKb2BVAd&Z zU#G*_mGWLbqY4Zg#OnCjO{S`+T;ul|aKi{kYUshS)_%vp%7!V0ig@kI0or7(!N8kS z?y@A57g-DQsG{Ing)an$D}qC+!Lzb-k0dxdHyrF+UyeAdK{YK7GVPg6M3-6*g7P?< zQqRfTaPZvZ2c}2!VZH(jgf;|?d%x`5V&QDAkd2rS- zroJ{@-1$3pnN>xZtkWggLt0-x{zyk4WcX0dcv?I@gxnHreM#z!?;BPX z_AEVX_|Q#a6YkMvv5sI%=Se?aQB2@@kA8W<#F&zEXAxVMUPv2HcI1u*{Wb4KPua`M zBb=6kO*S0uPaj=M12+bnPfdUG@I=ifq0vL+NMA27pQ6{J*gF%zgz>xm3I+gpn9 zf5)@aS}dgr8+(u!Tt~3$Xpb-|cTB&QjE);|YAJ|{4Z@$XRW*se6JqA%og=iJshJir z^Fk!NfkP7tz8ZrNcfFG}8Jsq{7|eEzb|;n`5ZWT|^F#asUG53)_WNOn&eeXbxLSC$ zE#Wi%Ko$c_diNE)`BewLcc5`sIdLvhnor3wnNTlx&NH3!`0;%{PB{47&3=igohUh~ zT_#P}5Ps2^Z`b+zL~7iQPRY?-Wfj*nMEg2FIv-?ji~oL#@v4P4i+Vm_^a;t1d5{oj zTGxRm=xt=%Wl7(v1$0(cn}^~a`mxrEvev3u?e`ZRn$5>Ob^N)wi8gsceB6wZxF&Uj z0y^HHiX?7Z0lqiZo=(rVRom1#)^CJo45%&T1&uduT+zlztT*Wn2XzC6-=L`K<|1Eq z61sY~t%2YI{!vkjU@;uCvhaFZr{1A&@ufdKWAkg+hgA(i{Xqn(oK1dL1 z@=QdzI!-|*xHJpFh#j_E``1ErJed;fsrmuccqEY}lZEDCzzeY9PA_XZ)rCo;U(jLK zC@eBxW8T2T3QK~oyka^NdHR4;xloVGQA_BAAfxWTr|Q2)6W18+nb z8LKf%F|Qom!Jq(*mEnR_sXa2O1dA?gU$SMPeOuNN$HxWhEnsOc#lakT9@(rXkbsh4 zc|Kz#3~681hX#W4#{8t&5Z}AO7fa~Wqe;N}rQDFDWt|w!I2O=#vEdf`4LBkFdBULv zly zCj-7hS-SOHrTw?!)ycj$%U5J?#{0<_9eA%gsEN3ikeEYM6B0aThY6Wg_A|uh4ND{x zO`_1PsWBF*{Ean?*tqqIg@*yGqy*Odw^b_+{dQ0>VkeJc-^;wbTz^aM5Wx}!&s`c$ zC*|3ciSHks=Qj6Dake_z3e9Has*FJVY0XL=j( zzbn0l=(LL0CWV}~OZRDpEAOD00dM0|OyoeYmi5QRPOvDsy$us9? q+i2{vEw+iYh1P@pul_S36=DPNba2-lifj3&g}S>QcPVwIrv4N7Pa@6$ literal 0 HcmV?d00001 diff --git a/docs/assets/images/logo.png b/docs/assets/images/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..cd053e21aa77857ce2c655066fcbb84694ffd7ab GIT binary patch literal 5610 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 literal 0 HcmV?d00001 diff --git a/docs/index.md b/docs/index.md index 7654dd9..4e79286 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,11 +18,12 @@ Ufpy (Useful Python) - is a package for simplifying Python programs using many u Now Ufpy has these features: - [`UDict`](useful_classes/udict.md "Useful dict."). -- [`UStack`](useful_classes/ustack.md "Useful stack."). +- [`uSTL` package](uSTL/index.md). + - [`Stack`](uSTL/stack.md). - Generators of classes methods: - - [`cmp_generator`](generators.md "Compare generator. In latest python version were deleted __cmp__ method. With this generator you can use __cmp__ in your class") - - [`r_generator`](generators.md "Reverse generator. Generating __r...__ methods for math operations") - - [`i_generator`](generators.md "I methods generator. Generating __i...__ method for math operations") + - [`cmp_generator`](useful_features/generators.md "Compare generator. In latest python version were deleted __cmp__ method. With this generator you can use __cmp__ in your class") + - [`r_generator`](useful_features/generators.md "Reverse generator. Generating __r...__ methods for math operations") + - [`i_generator`](useful_features/generators.md "I methods generator. Generating __i...__ method for math operations") - [many protocols for type hinting.](type_checking/protocols.md) - [many type alias for type hinting.](type_checking/type_alias.md) diff --git a/docs/uSTL/index.md b/docs/uSTL/index.md new file mode 100644 index 0000000..9b47533 --- /dev/null +++ b/docs/uSTL/index.md @@ -0,0 +1,7 @@ +# Introduction + +{-- +`uSTL` package is ... +--} + +Under development! \ No newline at end of file diff --git a/docs/uSTL/stack.md b/docs/uSTL/stack.md new file mode 100644 index 0000000..74089a2 --- /dev/null +++ b/docs/uSTL/stack.md @@ -0,0 +1,8 @@ +--- +title: Stack[VT] + +tags: + - uSTL +--- + +# class Stack[VT] diff --git a/docs/useful_classes/udict.md b/docs/useful_classes/udict.md index 10e39a7..b7fd752 100644 --- a/docs/useful_classes/udict.md +++ b/docs/useful_classes/udict.md @@ -1,23 +1,13 @@ --- -title: UDict +title: UDict[KT, VT, CDV] tags: - useful class --- -# `UDict` class +# class UDict[KT, VT, CDV] -!!! note "UDict as generic" - You can use `UDict` as `Generic`, because of it, there are 3 `TypeVar`s: KT, VT, CDV. - - KT and VT is key type and value type. In inbuilt `dict` there are KT and VT type vars. - CDV is class defaul value. - - In this documentation KT, VT and CDV will be using in methods. - -## class UDict[KT, VT, CDV] - -```python +```py class UDict(dictionary: AnyDict[KT, VT]) # (1)! class UDict(dictionary: AnyDict[KT, VT], *, default: CDV) class UDict(**kwargs: VT) @@ -34,6 +24,14 @@ class UDict(*, default: CDV, **kwargs: VT) --- +!!! note "UDict as generic" + You can use `UDict` as `Generic`, because of it, there are 3 `TypeVar`s: KT, VT, CDV. + + KT and VT are key type and value type. In inbuilt `dict` there are KT and VT type vars. + CDV is class default value. + + In this documentation KT, VT and CDV will be used in methods. + Create UDict object. If `default`, when not existent keys is given in getting item, method will return `default`. @@ -42,7 +40,7 @@ getting item, method will return `default`. d = UDict(hello=world, hi=python, default=10) ``` -## (property, settable) dictionary: dict[KT, VT] +## (property, settable) dictionary: dict[KT, VT] { data-toc-label="dictionary" } UDict's dictionary. @@ -56,16 +54,16 @@ UDict's dictionary. You can use UDict to set dictionary !!! example - ```python + ```py d.dictionary = UDict({1: 7}) ``` -## (property, settable) keys: list[KT] +## (property, settable) keys: list[KT] { data-toc-label="keys" } UDict's keys !!! example - ```python + ```py print(d.keys) d.keys = [1, 2] ``` @@ -74,16 +72,16 @@ UDict's keys You can use tuples to set keys !!! example - ```python + ```py d.keys = 1, 2 ``` -## (property, settable) values: list[VT] +## (property, settable) values: list[VT] { data-toc-label="values" } UDict's values !!! example - ```python + ```py print(d.values) d.values = [7, 2] ``` @@ -92,16 +90,16 @@ UDict's values You can use tuples to set values !!! example - ```python + ```py d.values = 7, 2 ``` -## (property, settable) items: list[tuple[KT, VT]] +## (property, settable) items: list[tuple[KT, VT]] { data-toc-label="items" } UDict's items. !!! example - ```python + ```py print(d.items) d.items = [(1, 7), (2, 2)] ``` @@ -110,22 +108,22 @@ UDict's items. You can use tuples to set items or you can use tuples or lists with lists !!! example - ```python + ```py d.items = (1, 7), (2, 2) d.items = [1, 7], [2, 2] ``` -## (property, settable) default: CDV +## (property, settable) default: CDV { data-toc-label="default" } UDict's default value !!! example - ```python + ```py print(d.default) d.default = 'null' ``` -## reverse() -> UDict[KT, VT, CDV] +## reverse() -> UDict[KT, VT, CDV] { data-toc-label="reverse()" } Reverses UDict and returns it. (1) { .annotate } @@ -133,37 +131,37 @@ Reverses UDict and returns it. (1) 1. !!! question "How UDict is being reversing?" Just is being reversing items - `#!python u{'hello': 1, 'hi': 2}` -> `#!python u{'hi': 2, 'hello': 1}` (reversed) + `#!py u{'hello': 1, 'hi': 2}` -> `#!py u{'hi': 2, 'hello': 1}` (reversed) !!! warning - `#!python reverse()` edits UDict. If you don't want to reverse UDict use [`#!python reversed()`](#reversed-udictkt-vt-cdv) method instead. + `#!py reverse()` edits UDict. If you don't want to reverse UDict use [`#!py reversed()`](#reversed-udictkt-vt-cdv) method instead. !!! example - ```python + ```py d.reverse() print(d) # prints reversed UDict ``` -## reversed() -> UDict[KT, VT, CDV] +## reversed() -> UDict[KT, VT, CDV] { data-toc-label="reversed()" } Returns reversed UDict !!! example - ```python + ```py print(d.reversed()) ``` -!!! tip "Get reversed UDict with inbuilt `#!python reversed()` and `#!python ~` operator" - You can get reversed UDict with inbuilt `#!python reversed()` and with invert operator (`~`). +!!! tip "Get reversed UDict with inbuilt `#!py reversed()` and `#!py ~` operator" + You can get reversed UDict with inbuilt `#!py reversed()` and with invert operator (`~`). !!! example ``` print(~d) print(reversed(d)) print(d.reversed() == reversed(d)) # True ``` - [Read more about `#!python reversed()` and `#!python ~` support in UDict](#magic-methods) + [Read more about `#!py reversed()` and `#!py ~` support in UDict](#__invert__-udictkt-vt-cdv) -## sort() -> UDict[KT, VT, CDV] +## sort() -> UDict[KT, VT, CDV] { data-toc-label="sort()" } Sorts UDict and returns it. (1) { .annotate } @@ -171,28 +169,28 @@ Sorts UDict and returns it. (1) 1. !!! question "How UDict is being sorting?" Just are being sorting items by keys. - `#!python u{'b': 1, 'a': 2}` -> `#!python u{'a': 2, 'b': 1}` (sorted) + `#!py u{'b': 1, 'a': 2}` -> `#!py u{'a': 2, 'b': 1}` (sorted) !!! warning - `#!python sort()` edits UDict. If you don't want to sort UDict use [`#!python sorted()`](#sorted-udictkt-vt-cdv) method instead. + `#!py sort()` edits UDict. If you don't want to sort UDict use [`#!py sorted()`](#sorted-udictkt-vt-cdv) method instead. !!! example - ```python + ```py print(d.sort()) ``` -## sorted() -> UDict[KT, VT, CDV] +## sorted() -> UDict[KT, VT, CDV] { data-toc-label="sorted()" } Returns sorted UDict !!! example - ```python + ```py print(d.sorted()) ``` -## get() +## get() { data-toc-label="get(*, key, index, value, default)" } -```python +```py def get(*, key: KT) -> VT | CDV def get(*, key: KT, default: DV) -> VT | DV def get(*, index: int) -> VT | CDV @@ -205,16 +203,16 @@ def get(*, value: VT, default: DV) -> KT | DV If you use 0 or 2 or 3 of this arguments (`key`, `index`, `value`), method will raise `ValueError` Arguments: -#### `key: KT` +#### `key: KT` { data-toc-label="key" } UDict value's key to find. !!! example - ```python + ```py print(d.get(key='key')) # same that d['key'] ``` -#### `index: int` +#### `index: int` { data-toc-label="index" } UDict value's index to find @@ -222,44 +220,315 @@ UDict value's index to find Indexes are starting from 1. Index of first element of UDict is 1. !!! failure "`index` argument more than UDict length" - If you use `index` argument make sure that `index` are less than UDict length. Otherwise `#!python get()` + If you use `index` argument make sure that `index` are less than UDict length. Otherwise `#!py get()` will raise `IndexError` !!! example - ```python + ```py print(d.get(index=2)) # second value of UDict ``` -#### `value: VT` +#### `value: VT` { data-toc-label="value" } UDict key's value to find !!! example - ```python + ```py print(d.get(value=1)) # if d = UDict{'hello': 1}, this will be 'hello' ``` +#### `default: DV` { data-toc-label="default" } + +Default value, if the result was not found. If not provided, then `default` is `UDict.default` property. + +!!! example + ```py + d = UDict(hello=1, hi=2, default=-1) + print(d.get(key='hell')) # -1 + print(d.get(key='hell', default=None)) # None + ``` + +## is_empty() -> bool { data-toc-label="is_empty()" } + +Returns `True` if the UDict is empty (`len(UDict) == 0`), otherwise returns `False`. + +!!! example + ```py + d = UDict(hello=1) + d2 = UDict() + print(d.is_empty()) # False + print(d2.is_empty()) # True + ``` + +!!! tip "Convert UDict to `#!py bool`" + You can convert UDict to `#!py bool` or use UDict in `#!py if` statement. If `#!py UDict.is_empty() == True` + then `#!py bool(UDict)` is False and by contrast. Same in `#!py if` because of `#!py if x` is the equivalent + of `#!py if bool(x)` + + !!! example + ```py + # d is from code above + print(bool(d)) # True + if d: + print("d is True") # d is True + ``` + ## Magic methods Currently, UDict supports all these magic methods: -### _\_call__(func: Callable[[KT, VT], VT]) -> UDict[KT, VT, CDV] +### \_\_call\_\_(func: Callable[[KT, VT], VT]) -> UDict[KT, VT, CDV] { data-toc-label="\_\_call\_\_(func)" } Returns new UDict, but all values generated with `func` function. First argument: key, second: value. Arguments: -#### `func: (KT, VT) -> VT` +#### `func: (KT, VT) -> VT` { data-toc-label="func" } First argument of function is key, second is value. Returns new value !!! example - ```python + ```py def f(k, v): return v * 2 d = d(f) # multiply all values by 2 ``` +### \_\_neg\_\_() -> UDict[KT, int | float, CDV] { data-toc-label="\_\_neg\_\_()" } + +Negates all values (if they support the `-` operator) to their opposite numbers. + +!!! example + ```py + d = UDict(hello=1, hi=-2) + print(-d) # u{'hello': -1, 'hi': 2} + ``` + +### \_\_invert\_\_() -> UDict[KT, VT, CDV] { data-toc-label="\_\_invert\_\_()" } + +The equivalent of [`#!py reversed()`](#reversed-udictkt-vt-cdv) + +!!! example + ```py + print(~d) + ``` + +### \_\_reversed\_\_() -> UDict[KT, VT, CDV] { data-toc-label="\_\_reversed\_\_()" } + +The equivalent of [`#!py reversed()`](#reversed-udictkt-vt-cdv) + +!!! example + ```py + print(reversed(d)) + ``` + +### \_\_getitem\_\_(key: KT | int | slice) -> UDict[KT, VT, DV] | VT { data-toc-label="\_\_getitem\_\_(key)" } + +Returns the value for a single key, or a UDict for multiple keys provided with a slice. + +!!! warning "Indexes starting at 1." + +Arguments: +#### `key: KT | int | slice` { data-toc-label="key" } + +Value's key or index to get or values's indexes slice to get. + +!!! example + ```py + print(d['hello']) + print(d[1:2]) + ``` + +!!! tip "Using indexes" + You can also use indexes in `#!py __getitem__()`. + + !!! failure + Keep in mind that indexes are using after the keys with the given value were not found. + !!! example + If you have `#!py 1` key, `d[1]` syntax will use `#!py 1` how key, not index. If you want to use index in + all ways, use [`#!py get()`](#get) instead. + + !!! example + ```py + d = UDict(hello=1, hi=9) + print(d[2]) # 9 + ``` + +### \_\_setitem\_\_(key: KT | int | slice, value: VT | list[VT] | tuple[VT]) { data-toc-label="\_\_setitem\_\_(key, value)" } + +Sets the value or values for the given key or keys. + +#### `key: KT | int | slice` { data-toc-label="key" } + +Value's key or keys to set. This argument is the same with [`key` argument in `#!py __getitem__()` method](#key-kt-int-slice) + +#### `value: VT | list[VT] | tuple[VT]` { data-toc-label="value" } + +Value or values to set. + +!!! example + ```py + d = UDict(hello=2, hi=1) + d[2] = 'hello' + print(d['hi']) # 'hello' + d[:] = 'hello', 'world' + print(d) # u{'hello': 'hello', 'hi': 'world'} + ``` + +### \_\_delitem\_\_(key: KT | int | slice) { data-toc-label="\_\_delitem\_\_(key)" } + +Deletes items with the given key or keys. + +#### `key: KT | int | slice` { data-toc-label="key" } + +Item's key or keys to delete. This argument is the same with [`key` argument in `#!py __getitem__()` method](#key-kt-int-slice). + +### \_\_len\_\_() -> int { data-toc-label="\_\_len\_\_()" } + +Returns the length of the UDict. + +!!! example + d = UDict(hello=1, hi=2) + print(len(d)) # 2 + +### \_\_iter\_\_() -> Iterator[tuple[KT, VT]] { data-toc-label="\_\_iter\_\_()" } + +Iterate over the UDict. The equivalent of `#!py items.__iter__()`. + +!!! example + ```py + for k, v in d: + print(f"Key: {k}\nValue: {v}") # Prints all keys and its values. + ``` + +### \_\_bool\_\_() -> bool { data-toc-label="\_\_bool\_\_()" } + +Returns whether the UDict is not empty. The equivalent of `#!py not is_empty()` + +!!! example + ```py + print(bool(d)) + if d: + print("D is not empty!") + ``` + +### \_\_contains\_\_(item: tuple[KT, VT] | list[KT | VT] | KT) -> bool { data-toc-label="\_\_contains\_\_(item)" } + +Checks whether the item or key is in the UDict. + +Arguments: +#### item: tuple[KT, VT] | list[KT | VT] | KT { data-toc-label="item" } +Item or item's key. + +!!! example + ```py + if ('key', 'value') in d: ... + if ['key', 'value'] in d: ... + if 'key' in d: ... + ``` + +### \_\_repr\_\_() -> str { data-toc-label="\_\_repr\_\_()" } + +Returns the string representation of the UDict. This allows the UDict to be used in `print()` and `repr()`. + +!!! example + ```py + d = UDict(hello=1) + print(d) # u{'hello': 1} + print(repr(d)) # Same + ``` + +### \_\_hash\_\_() -> int { data-toc-label="\_\_hash\_\_()" } + +Returns the hash for `#!py repr(UDict)`. The equivalent of `#!py repr(UDict).__hash__()`. + +### \_\_cmp\_\_(other: dict[KT, VT] | UDict[KT, VT, CDV]) -> int { data-toc-label="\_\_cmp\_\_(other)" } + +Used by `#!py @cmp_generator`, which generates comparison magic methods like `==`, `!=`, `>`, `>=`, `<`, `<=` operators. + +Comparing UDicts involves comparing their lengths, except for `#!py __eq__()`. + +!!! example + ```py + d = UDict(hello=1) + d2 = UDict(hello=1, hi=2) + print(d != d2) # True + print(d < d2) # True + print(d > d2) # False + ``` + +### \_\_eq\_\_(other: dict[KT, VT] | UDict[KT, VT, CDV]) -> bool { data-toc-label="\_\_eq\_\_(other)" } + +Checks whether UDicts are the same. (Overrides generated by `#!py @cmp_generator` magic method) + +!!! example + ```py + d = UDict(hello=1) + d2 = UDict(hello=1, hi=2) + print(d == d2) # False + print(d == d) # True + ``` + +!!! tip + You can use dict to compare with UDict. Method will automatically generate UDict from this dict + ```py + print(d == {'hello': 1}) # True + ``` + +### \_\_add\_\_(other: dict[KT, VT] | UDict[KT, VT, CDV]) -> UDict[KT, VT, CDV] { data-toc-label="\_\_add\_\_(other)" } + +Adds the dictionary or UDict's dictionary to the UDict's dictionary. This method also has `r` and `i` versions (`+=`). + +!!! example + ```py + print(d + {'hi': 2}) + print({'hi': 2} + d) + d += {'hi': 2} + ``` + *[KT]: Key type *[VT]: Value type *[CDV]: Class default value + +### \_\_sub\_\_(other: dict[KT, VT] | UDict[KT, VT, CDV]) -> UDict[KT, VT, CDV] { data-toc-label="\_\_sub\_\_(other)" } + +Subtracts the dictionary or UDict's dictionary from the UDict's dictionary. This method also has `r` and `i` versions (`-=`). + +!!! example + ```py + d = UDict(hello=1, hi=2) + print(d - {'hello': 1}) # u{'hi': 2} + d -= {'hello': 1} + print(d) # Same + ``` + +### \_\_mul\_\_(other: dict[KT, float | int] | UDict[KT, float | int, DV] | float | int) -> UDict[KT, SupportsMul, CDV] { data-toc-label="\_\_mul\_\_(other)" } + +Multiply all values by `other`, if `other` is `#!py int` or `#!py float`. +Multiply values with keys equals to `other` keys by `other` values, if `other` is `#!py dict` or UDict. +This method also have `r` and `i` version (`*=`) + +!!! warning + Make sure that your UDict's values supports multiply operator (`*`) + +!!! example + ```py + d = UDict(hello=1, hi=2) + print(d * 2) # {'hello': 2, 'hi': 4} + print(d * {'hi': 3}) # {'hello': 1, 'hi': 6} + ``` + +### \_\_truediv\_\_(other: dict[KT, float | int] | UDict[KT, float | int, DV] | float | int) -> UDict[KT, SupportsTrueDiv, CDV] { data-toc-label="\_\_truediv\_\_(other)" } + +Same that [`__mul__()`](#__mul__other-dictkt-float-int-udictkt-float-int-dv-float-int-udictkt-supportsmul-cdv), +but with divide operator (`/`). + +!!! warning + Make sure that your UDict's values supports divide operator (`/`) + +!!! example + ```py + d = UDict(hello=1, hi=2) + print(d / 2) # {'hello': 0.5, 'hi': 1} + print(d / {'hi': 4}) # {'hello': 1, 'hi': 0.5} + ``` diff --git a/docs/useful_classes/ustack.md b/docs/useful_classes/ustack.md index 3a5c7dc..5c17faa 100644 --- a/docs/useful_classes/ustack.md +++ b/docs/useful_classes/ustack.md @@ -1,8 +1,12 @@ --- -title: UStack +title: UStack[VT] (deprecated) tags: - useful class --- -# `UStack` class +{-- +# class UStack[VT] +--} + +UStack is deprecated in version 0.2 and will be deleted in version 0.5. Use [`uSTL.Stack`](../uSTL/stack.md) class instead. \ No newline at end of file diff --git a/docs/generators.md b/docs/useful_features/generators.md similarity index 100% rename from docs/generators.md rename to docs/useful_features/generators.md diff --git a/mkdocs.yml b/mkdocs.yml index f8e4278..aff6ec0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,10 +6,11 @@ repo_name: honey-team/ufpy theme: name: material + logo: assets/images/logo.png features: - content.code.copy - content.tooltips - - header.autohide + - content.code.annotate - search.suggest - navigation.tabs - navigation.tabs.sticky @@ -19,15 +20,15 @@ theme: - navigation.tracking - navigation.instant - navigation.instant.progress - - navigation.instant.prefetch - - navigation.instant.preview - toc.follow icon: repo: fontawesome/brands/github + annotation: material/plus-circle tag: typec: material/code-braces info: octicons/info-16 useful: simple/python + ustl: material/language-cpp palette: - media: "(prefers-color-scheme: light)" scheme: default @@ -46,6 +47,7 @@ extra: information: info useful class: useful useful feature: useful + uSTL: ustl version: provider: mike @@ -63,6 +65,7 @@ markdown_extensions: line_spans: __span use_pygments: true pygments_lang_class: true + - pymdownx.critic - pymdownx.details - pymdownx.inlinehilite - pymdownx.snippets