v1: Remove _async suffix from all methods, remove fire-n-forget counterparts, code improvements (#6)

ndonkoHenri · web-flow · commit 88fb80a6b403 · 2025-08-17T17:33:19.000-07:00
* configs

* remove fire-and-forget methods | remove _async in methods name

* updates

* fix: correct flashlight control flow and improve type checking in is_available method
diff --git a/.ci/patch_pubspec_version.py b/.ci/patch_pubspec_version.py
@@ -1,3 +1,7 @@
+# /// script
+# dependencies = ["pyyaml"]
+# ///
+
 import os
 import pathlib
 import sys
@@ -17,7 +21,7 @@
     "flet",
 ]
 
-with open(pubspec_path, "r") as f:
+with open(pubspec_path) as f:
     data = yaml.safe_load(f)
 
     # patch version
diff --git a/.ci/patch_toml_version.py b/.ci/patch_toml_version.py
@@ -1,3 +1,7 @@
+# /// script
+# dependencies = ["tomlkit"]
+# ///
+
 import os
 import pathlib
 import sys
@@ -14,7 +18,7 @@
 print(f"Patching TOML file {toml_path} to {ver}")
 
 # read
-with open(toml_path, "r") as f:
+with open(toml_path) as f:
     t = tomlkit.parse(f.read())
 
 # patch version
diff --git a/.docstr.yaml b/.docstr.yaml
@@ -0,0 +1,7 @@
+paths: src/flet_flashlight
+badge: ./docs/assets/badges/docs-coverage.svg
+skip_file_doc: True
+skip_private: False
+ignore_patterns: # Dict with key/value pairs of file-pattern/node-pattern
+  .*: __post_init__  # Ignore __post_init__ in all files
+fail_under: 50
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-      - dev
     paths:
       - 'LICENSE'
       - 'CHANGELOG.md'
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Deployed online documentation: https://flet-dev.github.io/flet-flashlight/
 - `Flashlight` control new properties: `on`, `on_error`
-- `Flashlight` control new methods: `is_available_async`
+- `Flashlight` control new methods: `is_available`
 - New exception classes:
     - `FlashlightException`
     - `FlashlightEnableExistentUserException`
@@ -32,4 +32,4 @@ Initial release.
 
 
 [0.2.0]: https://github.com/flet-dev/flet-flashlight/compare/0.1.0...0.2.0
-[0.1.0]: https://github.com/flet-dev/flet-flashlight/releases/tag/0.1.0
+[0.1.0]: https://github.com/flet-dev/flet-flashlight/releases/tag/0.1.0
diff --git a/README.md b/README.md
@@ -25,7 +25,9 @@ This package supports the following platforms:
 | Android  |     ✅     |
 | Web      |     ❌     |
 
-## Installation
+## Usage
+
+### Installation
 
 To install the `flet-flashlight` package and add it to your project dependencies:
 
@@ -44,3 +46,7 @@ To install the `flet-flashlight` package and add it to your project dependencies
     ```bash
     poetry add flet-flashlight
     ```
+
+### Examples
+
+For examples, see [these](./examples).
diff --git a/appveyor.yml b/appveyor.yml
@@ -3,23 +3,20 @@ image: ubuntu
 version: '0.1.{build}'
 
 environment:
+  PYTHON_VERSION: 3.12
   UV_PUBLISH_TOKEN:
     secure: 174ncAbF5IjSIkmioPt62jeSnzmTlRNchUkE4QdjDWH8xK1olYtySXLJpo2q95HcP7lWJky1hv4APESiRRHnBWoY0XRFafzM/mbCDMzG1tZXiXZmpP1qzHAtRP2QSCIg18xh1TMktraUdTi7sbJnjjRhqzgbW1k0kLBxKw79MPFBhYQ/TiGcmaYWZbWVZNY3HCUCb6Dt7bG1OE2Ul9rD1gvs55xwO9Oq9FOVA1VnMYw=
 
-stack:
-- python 3.12
-
 install:
 - source .ci/update_build_version.sh
-- python --version
-- python -m ensurepip --upgrade
-- pip3 install --upgrade tomlkit pyyaml
 - curl -LsSf https://astral.sh/uv/install.sh | sh
-- export PATH=$HOME/.local/bin:$PATH
+- export PATH="$HOME/.local/bin:$PATH"
+- uv python install $PYTHON_VERSION
+- uv python pin $PYTHON_VERSION
 
 build_script:
-- python .ci/patch_toml_version.py pyproject.toml $PYPI_VER
-- python .ci/patch_pubspec_version.py src/flutter/flet_*/pubspec.yaml $PKG_VER
+- uv run .ci/patch_toml_version.py pyproject.toml $PYPI_VER
+- uv run .ci/patch_pubspec_version.py src/flutter/flet_*/pubspec.yaml $PKG_VER
 - (cd src/flutter/* && dart pub get && dart analyze && cd -)
 - uv build
 
@@ -32,4 +29,4 @@ deploy_script:
 artifacts:
 - path: dist/*.whl
 
-test: off
+test: off
diff --git a/docs/flashlight.md b/docs/flashlight.md
@@ -1 +1,9 @@
-::: flet_flashlight.flashlight.Flashlight
+## Examples
+
+### Example 1
+
+```python title="example_1.py"
+--8<-- "examples/flashlight_example/src/example_1.py"
+```
+
+::: flet_flashlight.flashlight.Flashlight
diff --git a/docs/index.md b/docs/index.md
@@ -44,9 +44,6 @@ To install the `flet-flashlight` package and add it to your project dependencies
     poetry add flet-flashlight
     ```
 
+### Examples
 
-## Example
-
-```python title="main.py"
---8<-- "examples/flashlight_example/src/main.py"
-``` 
+See [these](flashlight.md#examples).
diff --git a/examples/flashlight_example/src/example_1.py b/examples/flashlight_example/src/example_1.py
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -114,6 +114,11 @@ plugins:
       alias_type: symlink
   - glightbox
   - section-index
+  - external-images:
+      mappings:
+        - source_dir: examples
+          target_url_path: examples
+          include_exts: [ ".png", ".gif", ".svg" ]
   - mkdocstrings:
       default_handler: python_xref
       handlers:
@@ -139,7 +144,6 @@ plugins:
             preload_modules: [ flet ]
             filters:
               - "!^_"   # Exclude private members starting with only one underscore
-              - "!get_event_field_type"
             extensions:
               - griffe_modernized_annotations
               - griffe_warnings_deprecated
@@ -190,3 +194,4 @@ markdown_extensions:
   - pymdownx.tasklist:
       custom_checkbox: true
   - pymdownx.tilde
+  - pymdownx.blocks.caption
diff --git a/pyproject.toml b/pyproject.toml
@@ -52,13 +52,17 @@ docs = [
     "markdown-exec[ansi] >=1.11.0",
     "pydocstyle >=6.3.0",
     "linkcheckmd >=1.4.0",
+    "mkdocs-external-images",
     { include-group = 'docs-coverage' },
 ]
 all = [
     { include-group = 'dev' },
     { include-group = 'docs' },
 ]
 
+[tool.uv.sources]
+mkdocs-external-images = { git = "https://github.com/flet-dev/mkdocs-external-images", tag = "v0.2.0" }
+
 [build-system]
 requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
diff --git a/src/flet_flashlight/flashlight.py b/src/flet_flashlight/flashlight.py
@@ -1,4 +1,3 @@
-import asyncio
 from typing import Optional
 
 import flet as ft
@@ -39,11 +38,11 @@ class Flashlight(ft.Service):
     contains information on the error.
     """
 
-    async def turn_on_async(self):
+    async def turn_on(self):
         """
         Turns the flashlight on.
         """
-        r = await self._invoke_method_async("on")
+        r = await self._invoke_method("on")
         if r is True:
             self.on = True
         else:  # error occured
@@ -56,17 +55,11 @@ async def turn_on_async(self):
             else:
                 raise FlashlightEnableException(error_msg)
 
-    def turn_on(self):
-        """
-        Turns the flashlight on.
-        """
-        asyncio.create_task(self.turn_on_async())
-
-    async def turn_off_async(self):
+    async def turn_off(self):
         """
         Turns the flashlight off.
         """
-        r = await self._invoke_method_async("off")
+        r = await self._invoke_method("off")
         if r is True:
             self.on = False
         else:  # error occured
@@ -79,32 +72,21 @@ async def turn_off_async(self):
             else:
                 raise FlashlightDisableException(error_msg)
 
-    def turn_off(self):
-        """
-        Turns the flashlight off.
-        """
-        asyncio.create_task(self.turn_off_async())
-
-    async def toggle_async(self):
+    async def toggle(self):
         """
         Toggles the flashlight on and off.
         """
         if self.on:
-            await self.turn_off_async()
-        await self.turn_on_async()
-
-    def toggle(self):
-        """
-        Toggles the flashlight on and off.
-        """
-        asyncio.create_task(self.toggle_async())
+            await self.turn_off()
+        else:
+            await self.turn_on()
 
-    async def is_available_async(self):
+    async def is_available(self):
         """
         Checks if the flashlight is available on the device.
         """
-        r = await self._invoke_method_async("is_available")
-        if r is bool:
+        r = await self._invoke_method("is_available")
+        if isinstance(r, bool):
             return r
         else:  # error occured
             error_msg = r.get("error_msg")
