kungfu-fp 1.0.0__tar.gz

kungfu_fp-1.0.0/.github/actions/install-dependencies/action.yml

@@ -0,0 +1,15 @@
+name: Install uv and dependencies
+
+runs:
+  using: composite
+  steps:
+    - uses: hynek/setup-cached-uv@v2
+      with:
+        cache-suffix: -3.13-cache
+        cache-dependency-path: "**/uv.lock"
+
+    - name: "Install dependencies"
+      run: |
+        uv venv --python 3.13
+        uv sync --all-groups --dev
+      shell: bash

kungfu_fp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+'on':
+  push:
+    branches:
+      - main
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  lock-file:
+    name: "Lock uv"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: asottile/workflows/.github/actions/fast-checkout@v1.8.1
+      - uses: ./.github/actions/install-dependencies
+      - run: uv lock --locked
+
+  linting:
+    name: "Linting"
+    runs-on: ubuntu-latest
+    needs: lock-file
+    steps:
+      - uses: asottile/workflows/.github/actions/fast-checkout@v1.8.1
+      - uses: ./.github/actions/install-dependencies
+
+      - name: Load ruff cache
+        id: cached-ruff
+        uses: actions/cache@v4
+        with:
+          key: ruff-3.13-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}
+          path: .ruff_cache
+
+      - name: "Run ruff"
+        run: uvx ruff check .
+
+  type-checking:
+    name: "Type-checking"
+    runs-on: ubuntu-latest
+    needs: lock-file
+    steps:
+      - uses: asottile/workflows/.github/actions/fast-checkout@v1.8.1
+      - uses: ./.github/actions/install-dependencies
+      - run: uv run pyright --level error
+
+  tests:
+    name: "Testing"
+    runs-on: ubuntu-latest
+    needs: lock-file
+    steps:
+      - uses: asottile/workflows/.github/actions/fast-checkout@v1.8.1
+      - uses: ./.github/actions/install-dependencies
+
+      - name: Load pytest cache
+        id: cached-pytest
+        uses: actions/cache@v4
+        with:
+          key: pytest-3.13-${{ runner.os }}
+          path: .pytest_cache
+
+      - name: "Run pytest"
+        run: uv run pytest tests

kungfu_fp-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__
+.mypy_cache
+.DS_Store
+.coverage
+dist/
+.pytest_cache
+.ruff_cache

kungfu_fp-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,73 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+        stages: [ pre-commit, pre-push ]
+      - id: check-ast
+        stages: [ pre-commit ]
+      - id: trailing-whitespace
+        stages: [ pre-commit ]
+      - id: end-of-file-fixer
+        stages: [ pre-commit ]
+
+  - repo: local
+    hooks:
+      - id: uv
+        name: uv-lock
+        description: "Run uv lock"
+        entry: uv lock --locked
+        language: system
+        pass_filenames: false
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: pyright
+        name: pyright
+        description: "Run 'pyright' for Python type checking"
+        entry: uv run pyright kungfu --level error
+        pass_filenames: false
+        language: system
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: pytest
+        name: pytest
+        description: "Run tests for testing code"
+        entry: uv run pytest tests
+        language: system
+        pass_filenames: false
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: ruff
+        name: ruff-isort
+        description: "Run 'ruff --select I --select F401 --fix' for extremely fast Python sorting imports"
+        entry: uv run ruff check --select I --select F401 --fix
+        language: system
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: ruff
+        name: ruff-sortall
+        description: "Run 'ruff check --select RUF022 --fix' for extremely fast Python sorting dunder alls"
+        entry: uv run ruff check --select RUF022 --fix
+        language: system
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: ruff
+        name: ruff-format
+        description: "Run 'ruff format' for extremely fast Python formatting"
+        entry: uv run ruff format
+        language: system
+        types: [ python ]
+        stages: [ pre-commit ]
+
+      - id: ruff
+        name: ruff-check
+        description: "Run 'ruff-format' for extremely fast Python linting"
+        entry: uv run ruff check --fix
+        language: system
+        types: [ python ]
+        stages: [ pre-commit ]

kungfu_fp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arseny Kriuchkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kungfu_fp-1.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: kungfu-fp
+Version: 1.0.0
+Author: timoniq
+License-File: LICENSE
+Requires-Python: <4.0,>=3.13
+Requires-Dist: typing-extensions>=4.15.0
+Description-Content-Type: text/markdown
+
+# kungfu
+
+⚙️ Functional typing in Python!
+
+```python
+get_user()
+  .then(get_posts)
+  .ensure(lambda posts: len(posts) > 0, "User has no posts")
+  .map(lambda posts: sum(post.views for post in posts) / len(posts))
+  .unwrap()
+```
+
+## why kungfu?
+
+kungfu is based on the belief that raising exceptions should be avoided. So it defines a set of functional types needed to write better code. This type strategy grants you with higher control over your runtime.
+
+Panicking is the last recourse but for some obscure reason spawning exceptions each time you encounter something other than the all-successful behaviour became a norm in python code.
+
+Let's fix this up and instead of panicking do treat error-state as equal to successful-state. kungfu provides you with all you need to migrate to functional typing approach
+
+Improving control flow will definitely result in avoiding logical errors and getting better code readability: you start to see each kind of behaviour you get from the function.
+
+why "kungfu" as a name? writing in kungfu requires some discipline. kung fu literally meaning "hard work" reflects on this concept. through the hard work on gaining control over our types we get clarity and power
+
+## (📖) documentation
+
+See [documentation](/docs/index.md)
+
+See [examples](/examples/)
+
+## examples
+
+**howto** build monad chains:
+
+```python
+def get_user(user_id: int) -> Result[User, str]:
+    ...
+
+def get_posts(user: User) -> Result[list[Post], str]:
+    ...
+
+def get_average_views(user_id: int) -> Result[int, str]:
+    return (
+        get_user(user_id)
+        .then(get_posts)
+        .ensure(len, "User has no posts")
+        .map(lambda posts: sum(post.views for post in posts) / len(posts))
+    )
+
+avg_views = get_average_views().unwrap()
+```
+
+**howto** detalize function result:
+
+```python
+@unwrapping
+def send_funds(
+    sender_id: int, 
+    receiver_id: int, 
+    amount: decimal.Decimal,
+) -> Result[TransactionID, str]:
+    sender = get_user(sender_id).expect("Sender is undefined")
+    receiver = get_user(receiver_id).expect("Receiver is undefined")
+
+    if sender.get_balance().expect("Could not get sender balance") < amount:
+        return Error("Sender has not enough funds to complete transaction")
+    
+    return Ok(
+        create_transaction(sender, receiver, amount)
+        .unwrap()
+        .transaction_id
+    )
+```
+
+Contributions are welcome
+
+MIT licensed
+
+---
+
+# awesome kungfu projects
+
+[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/sindresorhus/awesome)
+
+These projects are awesome to extend kungfu environment:
+
+* **[nodnod](https://github.com/timoniq/nodnod)** - dependency injection with efficient nodes computation agents and dependency scoping
+
+* **[combinators.py](https://github.com/prostomarkeloff/combinators.py)** - build explicit functional pipelines
+
+These projects implement kungfu environment in their specific utility cases:
+
+* **[telegrinder](https://github.com/timoniq/telegrinder)** - telegram bot framework

kungfu_fp-1.0.0/docs/advanced.md

@@ -0,0 +1,30 @@
+# kungfu - advanced
+
+In order to use advanced methods, some theory needs to be explained.
+
+Monad (a concept that kungfu is build on), requires its implementation to have a `bind` method. In `kungfu`, its name is `then` which expresses this idea in terms of imperative reality much better. We can *link* a monad (a result / an option) to a functor that will transform a value but preserve the original error type.
+
+```python
+x: Result[int, str]
+
+def invalid_bind(value: int) -> Result[int, RuntimeError]:
+    # Here, the error type is changed. Therefore, this binding procedure cannot be used with the `x` instance
+    ...
+
+def normal_bind(value: int) -> Result[int, str]:
+    """Multiplies odd numbers by 2"""
+    if x // 2 == 0:
+        return Error("value cannot be even")
+    return x * 2
+
+
+x = Ok(3)
+
+x.then(normal_bind) # Ok(6) ( Result[int, str] )
+x.then(normal_bind).then(normal_bind)  # Error("value cannot be even")
+
+x = Error("Something has already went wrong ..")
+
+x.then(normal_bind) # Error("Something has already went wrong ..")
+x.then(normal_bind).then(normal_bind) # Error("Something has already went wrong ..")
+```

kungfu_fp-1.0.0/docs/index.md

@@ -0,0 +1,13 @@
+# kungfu - documentation
+
+Welcome! Here is the list of concepts implemented by kungfu in an order suggested to learn this library:
+
+1. [Result](/docs/result.md)
+
+2. [Option](/docs/option.md)
+
+3. [Unwrapping](/docs/unwrapping.md)
+
+4. [Sum](/docs/sum.md)
+
+5. [Advanced practices](/docs/advanced.md)

kungfu_fp-1.0.0/docs/option.md

@@ -0,0 +1,30 @@
+# kungfu - option
+
+`Option` is derived from [Result](/docs/result.md), but its error state is secluded to only one possible - the `Nothing` state. The value state of Option is called `Some`.
+You may be used to use None python value to create such sort of ambiguation, but this is not good for the programming environment we are trying to create as it lacks functional features.
+Due to the fact, that `Option` is derived from simple Result, we can use all of the features of Result in Option. We can create functional maps, unwrap variables and preserve control flow because of avoiding spawning exceptions what we would do, for example, in case when we would require variable not to be None in that paradigm we are trying to do away with.
+
+In order to work with Option we will need to import such components as `Option`, `Some`, `Nothing`:
+
+```python
+from kungfu import Option, Some, Nothing
+```
+
+Let's create a function that will receive an option string and map its value into an uppercase version if it is in the state of `Some`:
+
+```python
+def shout(msg: Option[str]) -> None:
+    print(msg.map(str.upper).unwrap_or("RRr"), "!!")
+
+shout(Nothing())  # RRr !!
+shout(Some("arseny"))  # ARSENY !!
+```
+
+---
+
+As Option is just a Result lacking an error type, an instance of `Result[T, Err]` can be casted into an instance of `Option[T]` with a simple cast expression (Nothing can be passed like this, because it suppresses arguments it receives on initialization):
+
+```python
+def to_option(result: Result[T, Err]) -> Option[T]:
+    return result.cast(Some, Nothing)
+```

kungfu_fp-1.0.0/docs/result.md

@@ -0,0 +1,100 @@
+# kungfu - Result
+
+## Theory
+
+`Result` is a key object needed to create names in two states: in a state of an error and in a state of a value.
+
+Probably, you may be used to spawn exceptions as soon as you encounter an error. This is a bad practice. Fntypes advices strongly against raising exceptions. Why?
+
+It's because they ruin control flow completely: exceptions, raised in a function, cannot be type-hinted, therefore we cannot see and guarantee to handle all the exceptions that appear from it. Thus, this makes us create abstract exception handlers *just in case*, which is definitely must be perceived as a bad practice.
+
+In order to keep our control flow in a good form, we are offered to use Result monad - which is an entity that can obtain 2 states: a value - when the function proceeded successfully, or an error of a specific type - in case a function encountered a problem.
+
+Therefore, two classes in `kungfu` exist to represent these states:
+
+1. `kungfu.Ok` - representing a successful case
+
+2. `kungfu.Error` - representing an error
+
+An ambiguative state of those two states is called `Result`.
+
+## Application
+
+Let's create a function which is going to divide two numbers, and instead of raising an exception when the divisor is zero, its going to form an error state of a result. Otherwise, `Ok` with a resulting number is returned.
+
+```python
+from kungfu import Result, Ok, Error
+
+# Result takes 2 type arguments:
+# first one is a type of value on success,
+# the second one is a type of error
+def divide(a: int, b: int) -> Result[float, str]:
+    if b == 0:
+        return Error("Divisor cannot be zero")
+    return Ok(a / b)
+```
+
+Now, when the function is called, it returns a Result of one of two possible values. Let's try different ways of handling it:
+
+```python
+x = divide(6, 2) # <Result: Ok(3)>
+y = divide(3, 0) # <Result: Error("Divisor cannot be zero")>
+
+# Function unwrap, tranforms this call back to two states: of an exception or an actual value,
+# Unless we are in a safe `unwrapped` scope.
+x.unwrap() # 3
+y.unwrap() # This is going to raise an exception: UnwrapError("Divisor cannot be zero")
+
+# Unwrap with an alternative *value*
+x.unwrap_or(10) # 3
+y.unwrap_or(10) # 10
+
+x.unwrap_or_none() # 3
+y.unwrap_or_none() # None
+
+# Unwrap with an alternative *result*
+x.unwrap_or_other(divide(8, 4)) # <Result: Ok(3)>
+y.unwrap_or_other(divide(8, 4)) # <Result: Ok(2)>
+
+# Map - apply map on result value returning a result of an altered value type
+# If result is in error state, mapper is not going to be applied
+lst = ["Eniki", "Beniki", "Eli", "Vareniki"]
+
+x.map(lambda n: lst[n]) # <Result: Ok("Vareniki")>
+y.map(lambda n: lst[n]) # <Result: Error("Divisor cannot be zero")>
+
+x.map(lambda n: lst[n]).map(str.upper) # <Result: Ok("VARENIKI")>
+
+# More map functions are going to be presented in 'docs/advanced'
+
+x.expect("Division failure") # Raises an exception: UnwrapError("Division failure")
+# Expect is needed to transform error types
+
+# .then - is an essential operation to compose multiple result returning functions
+# Probably you may know it as bind operation
+# Error type of those must be same !
+# Argument is of value type, returning result can be of a different type
+queue = []
+IndexType = type("IndexType", (int,), {})
+
+def send_to_queue(n: int) -> Result[int, str]:
+    if len(queue) > 9:
+        return Error("Too many numbers in queue!")
+    queue.append(n)
+    return Ok(len(queue) - 1) # index in queue
+
+x.then(send_to_queue) # <Result: Ok(IndexType(0))>
+x.then(send_to_queue).unwrap() # IndexType(1)
+
+
+# Cast
+# Through cast Result type can be converted to other two-states object
+# By default casts for `ok` and `error` states are echo-functions.
+# Thus, only one cast may be set
+
+# Cast returns a union of two states' types
+x.cast() # Will return the same union of Result[float, str]
+x.cast(Some, lambda _: Nothing()) # Will cast it into a Option-like type (quite useful)
+# OR a more elegant way (thanks to Nothing-type argument suppression)
+x.cast(Some, Nothing)
+```

kungfu_fp-1.0.0/docs/sum.md

@@ -0,0 +1,43 @@
+# kungfu - Sum
+
+`Sum` is a functional replacement for `Union` typehint. It has methods to enhance the control flow over union types. Some of these methods use head-tail notation due to the type-hinting restrictions.
+
+Sum can contain multiple types (let the number of types be called N), therefore it can be contracted to N-1 states. Let's review the methods we can use to do so.
+
+Head-tail notation is a notation that splits any set of data in two parts: head - the first element, and tail, that is a set of everything else. Therefore, if we consider a `Sum[A, B, C]`, its head will be `A`, and tail `[B, C]`.
+
+## `.only(type = default to *head*)`
+
+Only contracts the sum to a single type and returns a `Result[type, str]`
+
+```python
+x: Sum[A, B, C]
+
+x.only(B) # Result[B, str]
+x.only() # Result[A, str] (heading type of sum is A)
+```
+
+Now, when you understand the concept, the syntaxic replacement can be intruduced:
+
+```python
+x[B].expect("Can only be B")
+# Can be used interchangably with
+x.only(B).expect("Can only be B")
+```
+
+## `.detach()`
+
+Head ensures that sum is not of *head* type and returns a result with a value-state of sum of *tail* types.
+
+```python
+x.detach()  # Result[Sum[B, C], str]
+```
+
+## `.v`
+
+Returns a union (basically an intersection of all types of sum).
+
+```python
+x.v # Union[A, B, C]
+```
+

kungfu_fp-1.0.0/docs/unwrapping.md

@@ -0,0 +1,89 @@
+# kungfu - unwrapping
+
+Unwrapping is a way to manage control flow designed with kungfu monads in a more convenient manner.
+
+In theory, unwrapping is needed to create a syntaxic sugar that functions like `bind` method that defines a monad. In kungfu `bind` is known as `.then`. What it does, is it creates a binding between two functions returning a result of the same error type or option. If the current monad is in the state of error, the error is returned, if not, the value is passed into the function that is an argument in `then`. Let's look to the following example:
+
+```python
+def func1(a: int) -> Result[str, str]:
+    if a == 0:
+        return Error("a cannot be 0")
+    return Ok(str(a))
+
+def func2(a: int) -> Result[str, TypeError]:
+    ...
+
+def func3(b: str) -> Result[int, str]:
+    if not b.isdigit():
+        return Error("Not a digit")
+    return Ok(int(b))
+
+
+x: Result[int, str] = Ok(11)
+
+x.then(func1) # "11"
+x.then(func2) # Type checker: wrong error type
+x.then(func1).then(func3) # 11
+
+y: Result[int, str] = Error("Some error")
+
+y.then(func1) # Error("Some error")
+y.then(func1).then(func3) # Error("Some error")
+```
+
+Now, after we have understanding what `then` (or `bind`) is needed for, we can also comprehend the idea of a syntaxic sugar to apply this idea in a single scope, with no need to create multiple functions.
+
+The only thing we should bear in mind is that the error type must be always same. For `Option` error type is None. If we need to change error type, we can use `expect` function.
+
+In order to do that, `unwrapping` decorator is used:
+
+
+```python
+from kungfu import unwrapping, Result, Ok, Error, Option
+
+
+class User:
+    ...
+
+    def get_balance(self) -> Result[decimal.Decimal, str]:
+        ...
+
+
+@dataclass
+class Transaction:
+    transaction_id: TransactionID
+
+
+def get_user(sender_id: int) -> Option[User]:
+    ...
+
+
+def create_transaction(sender: User, receiver: User, amount: decimal.Decimal) -> Result[Transaction, str]:
+    ...
+
+
+@unwrapping
+def send_funds(
+    sender_id: int, 
+    receiver_id: int, 
+    amount: decimal.Decimal,
+) -> Result[TransactionID, str]:
+    sender = get_user(sender_id).expect("Sender is undefined") # marker 1
+    receiver = get_user(receiver_id).expect("Receiver is undefined")
+    if sender.get_balance().unwrap() < amount:  # marker 2
+        return Error("Sender has not enough funds to complete transaction")
+    
+    return Ok(
+        create_transaction(sender, receiver, amount)
+        .unwrap()
+        .transaction_id
+    )
+```
+
+In this example we have a function which is wrapped in unwrapping decorator, it means that all methods like `unwrap`, `expect` are now covered and if any monad on which such methods are called is in the state of error, it will result in returning an error state out of the function obtaining the scope.
+
+Let's look onto markers.
+
+marker 1. Here we see that get_user returns an Option, which is of error type None, it doesn't correspond to an error type `str` of `Result[TransactionID, str]`. Thus, we have to change it and do `expect`. Into expect we pass the new error which is of type `str`. If error will pop out of `get_user`, an error will be immediately returned out of `send_funds`.
+
+marker 2. Here, out of `get_balance` we get a result (`Result[decimal.Decimal, str]`) with a corresponding error type `str`. Thats the reason we can just do `unwrap`, and the error, if it appears, will be returned *as it is* out of the function `send_funds`.

kungfu_fp-1.0.0/examples/mappings.py

@@ -0,0 +1,26 @@
+from kungfu import Error, Nothing, Option, Result, Some
+
+
+def map_error(result: Result[int, str]) -> Option[int]:
+    return result.cast(Some, Nothing)
+
+
+def map_value(result: Result[int, str]) -> Result[str, str]:
+    return result.map(str)
+
+
+def map_or(result: Result[int, str]) -> int:
+    return result.map_or(0, lambda x: x + 1).unwrap()
+
+
+def get_n() -> Result[int, str]:
+    return Error("Something happened")
+
+
+n = get_n()
+
+
+print(map_error(n))  # Nothing()
+print(map_value(n))  # Error("Something happened")
+print(map_or(n))  # 0
+print(n.cast().cast().cast())  # Error("Something happened")

kungfu_fp-1.0.0/examples/misc.py

@@ -0,0 +1,12 @@
+from kungfu import Error, Ok, Pulse
+
+
+def send_message(text: str) -> Pulse[str]:
+    if not text:
+        return Error("text is empty")
+    return Ok()
+
+
+result = send_message("hi!!!")
+
+print(result)

kungfu_fp-1.0.0/examples/option_unwrapping.py

@@ -0,0 +1,25 @@
+import random
+
+from kungfu import Error, Nothing, Ok, Option, Result, Some, is_err, unwrapping
+
+
+@unwrapping
+def calculate_something(arr: list[Option[int]]) -> Result[int, str]:
+    if is_err(arr[0]):
+        return Error("Invalid first element")
+    s = arr[0].unwrap()
+    for coeff in arr[1:]:
+        s += s * coeff.unwrap_or(0)
+    return Ok(s)
+
+
+@unwrapping
+def calculate_over_something(x: Option[int], count: int) -> Option[int]:
+    lst: list[Option[int]] = [x]
+    for i in range(count):
+        lst.append(Some(lst[len(lst) - 1].unwrap_or(0) + random.randint(15, 19)))
+    return Some(calculate_something(lst).unwrap())
+
+
+print(calculate_over_something(Some(10), 10).unwrap_or_none())  # *big number*
+print(calculate_over_something(Nothing(), 10).unwrap_or_none())  # None