fastled 1.1.37__tar.gz → 1.1.39__tar.gz

{fastled-1.1.37/src/fastled.egg-info → fastled-1.1.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastled
-Version: 1.1.37
+Version: 1.1.39
 Summary: FastLED Wasm Compiler
 Home-page: https://github.com/zackees/fastled-wasm
 Maintainer: Zachary Vorhies
@@ -61,60 +61,155 @@ pip install fastled
 
 **Note that you may need to install x86 docker emulation on Mac-m1 and later, as this is an x86 only image at the prsent.**
 
-# Use
+# Command Line Use
 
 Change to the directory where the sketch lives and run, will run the compilation
 on the web compiler.
 
 ```bash
+# This will use the web-compiler, unless you have docker installed in which case a local
+# server will be instantiated automatically.
 cd <SKETCH-DIRECTORY>
 fastled
 ```
 
-Or if you have docker you can run a server automatically.
+Forces the local server to to spawn in order to run to do the compile.
 
 ```bash
 cd <SKETCH-DIRECTORY>
-fastled --local
+fastled --local  # if server doesn't already exist, one is created.
 ```
 
 You can also spawn a server in one process and then access it in another, like this:
 
 ```bash
-fastled --server
+fastled --server  # server will now run in the background.
 # now launch the client
-fastled examples/wasm --local
+fastled examples/wasm --local  # local will find the local server use it do the compile.
 ```
 
 After compilation a web browser windows will pop up. Changes to the sketch will automatically trigger a recompilation.
 
-# Hot reload by default
+# Python Api
+
+**Compiling through the api**
+```python
+
+from fastapi import Api, CompileResult
+
+out: CompileResult = Api.web_compile("path/to/sketch")
+print(out.success)
+print(out.stdout)
+
+```
+
+**Launching a compile server**
+```python
+
+from fastapi import Api, CompileServer
+
+server: CompileServer = Api.spawn_server()
+print(f"Local server running at {server.url()}")
+server.web_compile("path/to/sketch")  # output will be "path/to/sketch/fastled_js"
+server.stop()
+```
+
+**Launching a server in a scope**
+```python
+
+from fastapi import Api
+
+# Launching a server in a scope
+with Api.server() as server:
+    server.web_compile("path/to/sketch")
+
+```
+
+**Initializing a project example from the web compiler**
+```python
+
+from fastapi import Api
+
+examples = Api.get_examples()
+print(f"Print available examples: {examples}")
+Api.project_init(examples[0])
+
+
+```
+
+**Initializing a project example from the CompileServer**
+```python
+
+from fastapi import Api
+
+with Api.server() as server:
+    examples = server.get_examples()
+    server.project_init(examples[0])
+
+```
+
+**LiveClient will auto-trigger a build on code changes, just like the cli does**
+```python
+
+# Live Client will compile against the web-compiler
+from fastapi import Api, LiveClient
+client: LiveClient = Api.live_client(
+    "path/to/sketch_directory",
+)
+# Now user can start editing their sketch and it will auto-compile
+# ... after a while stop it like this.
+client.stop()
+```
+
+**LiveClient with local CompileServer**
+```python
+
+# Live Client will compile against a local server.
+from fastapi import Api, LiveClient
+
+with Api.server() as server:
+    client: LiveClient = Api.live_client(
+        "path/to/sketch_directory",
+        host=server
+    )
+    # Now user can start editing their sketch and it will auto-compile
+    # ... after a while stop it like this.
+    client.stop()
+```
+
+# Features
+
+## Hot reload by default
 
 Once launched, the compiler will remain open, listening to changes and recompiling as necessary and hot-reloading the sketch into the current browser.
 
 This style of development should be familiar to those doing web development.
 
-# Hot Reload for working with the FastLED repo
+## Hot Reload fastled/src when working in the FastLED repo
 
 If you launch `fastled` in the FastLED repo then this tool will automatically detect this and map the src directory into the
 host container. Whenever there are changes in the source code from the mapped directory, then these will be re-compiled
 on the next change or if you hit the space bar when prompted. Unlike a sketch folder, a re-compile on the FastLED src
 can be much longer, for example if you modify a header file.
 
-# Data
+## Big Data in `/data` directory won't be round-tripped
 
 Huge blobs of data like video will absolutely kill the compile performance as these blobs would normally have to be shuffled
 back and forth. Therefore a special directory `data/` is implicitly used to hold this blob data. Any data in this directory
 will be replaced with a stub containing the size and hash of the file during upload. On download these stubs are swapped back
-with their originals.
+with their originals during decompression.
 
 The wasm compiler will recognize all files in the `data/` directory and generate a `files.json` manifest and can be used
 in your wasm sketch using an emulated SD card system mounted at `/data/` on the SD Card. In order to increase load speed, these
-files will be asynchroniously streamed into the running sketch instance during runtime. The only caveat here is that although these files will be available during the setup() phase of the sketch, they will not be fully hydrated, so if you do a seek(end) of these files the results are undefined.
+files will be asynchroniously streamed into the running sketch instance during runtime. Files named with *.json, *.csv, *.txt will be
+immediately injected in the app before setup() is called and can be used immediatly in setup() in their entirety.
+
+All other files will be streamed in. The `Video` element in FastLED is designed to gracefully handle missing data streamed in through
+the file system.
 
 For an example of how to use this see `examples/SdCard` which is fully wasm compatible.
 
-# Compile Speed
+## Compile Speed
 
 The compile speeds for this compiler have been optimized pretty much to the max. There are three compile settings available to the user. The default is `--quick`. Aggressive optimizations are done with `--release` which will aggressively optimize for size. The speed difference between `--release` and `--quick` seems negligable. But `--release` will produce a ~1/3 smaller binary. There is also `--debug`, which will include symbols necessary for debugging and getting the C++ function symbols working correctly in the browser during step through debugging. It works better than expected, but don't expect to have gdb or msvc debugger level of debugging experience.
 
@@ -122,24 +217,22 @@ We use `ccache` to cache object files. This seems actually help a lot and is bet
 
 The compilation to wasm will happen under a lock. Removing this lock requires removing the platformio toolchain as the compiler backend which enforces it's own internal lock preventing parallel use.
 
-Simple syntax errors will be caught by the pre-processing step. This happens without a lock to reduce the single lock bottleneck.
-
-# Sketch Cache
+## Sketch Cache
 
-Sketchs are aggresively finger-printed and stored in a cache. White space, comments, and other superficial data will be stripped out during pre-processing and minimization for fingerprinting. This source file decimation is only used for finger
+Sketchs are aggressively finger-printed and stored in a cache. White space, comments, and other superficial data will be stripped out during pre-processing and minimization for fingerprinting. This source file decimation is only used for finger
 printing while the actual source files are sent to compiler to preserve line numbers and file names.
 
 This pre-processing done is done via gcc and special regex's and will happen without a lock. This will allow you to have extremely quick recompiles for whitespace and changes in comments even if the compiler is executing under it's lock.
 
-# Local compiles
+## Local compiles
 
 If the web-compiler get's congested then it's recommend that you run the compiler locally. This requires docker and will be invoked whenever you pass in `--local`. This will first pull the most recent Docker image of the Fastled compiler, launching a webserver and then connecting to it with the client once it's been up.
 
-# Auto updates
+## Auto updates
 
 In server mode the git repository will be cloned as a side repo and then periodically updated and rsync'd to the src directory. This allows a long running instance to stay updated.
 
-### Wasm compatibility with Arduino sketchs
+## Compatibility with Arduino sketchs
 
 The compatibility is actually pretty good. Most simple sketchs should compile out of the box. Even some of the avr platform includes are stubbed out to make it work. The familiar `digitalWrite()`, `Serial.println()` and other common functions work. Although `digitalRead()` will always return 0 and `analogRead()` will return random numbers.
 
@@ -163,6 +256,8 @@ A: A big chunk of space is being used by unnecessary javascript `emscripten` is
 
 # Revisions
   
+  * 1.1.39 - Added `LiveClient`, `fastled.Api.live_server()` will spawn it. Allows user to have a live compiling client that re-triggers a compile on file changes.
+  * 1.1.38 - Cleanup the `fastled.Api` object and streamline for general use.
   * 1.1.37 - `Test.test_examples()` is now unit tested to work correctly.
   * 1.1.36 - We now have an api. `from fastled import Api` and `from fastled import Test` for testing.
   * 1.1.35 - When searching for files cap the limit at a high amount to prevent hang.