Package: luminal
DescriptionLuminal offers developers the perfect solution to streamline and optimize their projects effortlessly by creating dynamic and modular plugins, a.k.aPhotons. The library has been meticulously created based on best practices and offers a rich set of features and capabilities.The library is composed of 100% pure Python code with no dependencies while also using common developer libraries for tests and documentation. This means Luminal can be seamlessly integrated intoanyexisting project, reduce development time, and save valuable resources. Furthermore, the library boasts 100% code statement and branch coverage with minimal#pragmatags. This feature ensures clean and efficient code, reducing even more development time. Not only that, but the library also includes comprehensive documentation of core features, covering private methods, metaclasses, utilities, and public-facing functions. It is the perfect solution for streamlining your projects and optimizing resources effortlessly, offering reliability, efficiency, and instant modular dynamism.Luminal has been engineered as a dynamic and modular framework, making it portable, and easier to couple and decouple plugins, a.k.a.Photons. This feature expands the functionality of the library, giving developers a way to customize their solutions, improve software flexibility, and optimize required resources to scale their projects. The extensible architecture of the library allows developers to make modifications to the code quickly and easily, enabling them to tailor the library's functionality to their specific needs. Furthermore, Luminal prioritizes security, utilizing modern checksum algorithms and object caches for instance tracking, providing transparency and reliable safety.NOTE:The code in this repository was written completely by a human being. 🎃IMPORTANT:This repository uses up-to-datePythonsyntax (version3.11.1). Furthermore, the code is structured and organized to maintain good readability and clear modularity. The repository offers comprehensive unit and integration tests using coverage, which run on every push on GitHub Actions. Thank you for being amazing! 😄📖 Features100% pure Python code with no depenencies ofanykind100% code statement and branch coverage with minimal#pragmatagsAsynchronous & multi-threaded libary allowing for efficient usage of resourcesAtomic reloading & monitoring by using thewatch_photons(path)methodSmall footprint with optimizations for supporting various project types and sizesDynamic and modular design which allows easy coupling and decoupling of pluginsAdvanced logging of operations and debugging methods to help quickly resolve issuesAdvanced error handling that gracefully provides useful information for debugging codeExtensible at its core for developers to easily modify and alter portions of code as they see fitSecurity oriented by using modern checksum algorithms and object caches for instance trackingCompletely documented library covering private methods, metaclasses, utils, and public facing functionsLuminal follows established standards for plugin development to ensure interoperability with other libraries🧃 ComingSoon- Photon encapsulation using serialization

- Photon protection scanning using machine learning

- Advanced performance metrics for project optimization

- Built-in analytics and reporting capabilities to monitor usage and performance

- Improved security measures such as two-factor authentication, encryption, and hashing⚙️ InstallationOverviewThe installation process for the Luminal libary is a straightforward process akin to most Python packages. There are also multiple way of installation offered for the libary in order to allow easier installs. Follow the steps below to get started:PackagingThe application usespipas a package manager, and all dependencies are explicitly listed in therequirements.txtfile.Manual InstallTo install the library manually you should follow these steps:Clone this repository to your local machine:git clone https://github.com/jasondrawdy/luminal.gitCreate a virtual environment:virtualenv venv && source venv/bin/activateInstall the dependencies:pip install -r requirements.txtOnce you have the library installed you can start creating photons of any type!Automatic InstallTo install viapiprun the following command:pip install luminalorpip3 install luminalGit branching and workflowsThis repository has a main branch, which represents the the stable version of the project, and a development branch where all new features are tested before they are merged into the main branch. Pull requests should be used for any suggested changes before being merged.📜 DocumentationPlease visit the following webpage for this repository below in order to view comprehensive documentation on the project. A number of code examples are also available in this project repository in order to better understand how to use the library correctly.https://luminal.readthedocs.io/en/latest/🧰 Library UsageUnit TestsThe repository contains a multitude of test cases intests.py— here's what the main code looks like:classProgram:# pragma: no coverdef__init__(self)->None:self._logger=Logger(__name__)self._stopwatch=Nonedef_spawn_sentinel(self:"Program"):self._logger.note("Spawning a sentinel...")sentinel=Sentinel()sentinel.authorized=Truesentinel.start()time.sleep(1)def_start_tests(self:"Program"):ifnotos.path.exists(PhotonLocations.main_directory):raiseDirectoryNotFoundError("Please make sure to create the 'demos' directory!")ifnotos.path.exists(PhotonLocations.basic_photon):raiseFileNotFoundError("Please make sure to create a 'luminal_basic.py' file in the"+"'demos' directory which inherits from the 'IPhoton' class.")ifnotos.path.exists(PhotonLocations.advanced_photon):raiseFileNotFoundError("Please make sure to create a 'luminal_advanced.py' file in the"+"'demos' directory which inherits from the 'IPhoton' class, "+"has another IPhoton class with relative imports n-directories down, "+"and also a normal class which is as advanced or basic to your liking.")unittest.main(verbosity=2)if__name__=="__main__":# pragma: no branchprogram=Program()program._spawn_sentinel()program._start_tests()This code has quite a few elements, however, they are necessary in order to run all tests in a clean and efficient manner. A mainProgramclass is constructed in order to encapsulate all of the specific operations we'll be performing during our testing sessions too. We define aLogger(__name__)so that way we can get feedback from any tests that call the logger's functions. Before starting any tests we spawn aSentinel()in order to remove (cleanup) unwanted files such as cached and compiled artifacts. Finally, we start running our tests granted that the provided folders and files are available.To run all tests there are actually a few different methods:Runpython tests.pyPerforms all tests defined within the script, but with no coverage results other than the console output.Alternatively, runcoverage --branch tests.pyPerforms all tests and creates a report of code and branch coverage.Runningcoverage htmlafter the tests will generate a nice results page for user viewing.PhotonsIn the context of the Luminal framework, a photon represents a modular and extensible component that developers can use to enhance their projects. It is a specialized class that follows certain conventions and inherits from theIPhotonbase class or its derivatives.A photon encapsulates a specific functionality, behavior, or feature within a project. It can interact with other photons and the Luminal framework to achieve complex operations or provide additional capabilities. By adhering to the defined metadata attributes, such asphoton_name,photon_author,photon_version,photon_description, andphoton_tags, photons provide valuable information about their purpose, usage, and compatibility.Here are some ways developers can benefit from using photons:Modularity and ReusabilityPhotons offer a modular approach to development by encapsulating specific functionalities. Developers can easily plug in or remove photons as needed, promoting code reusability and maintaining clean project structure. With dynamic hotswapping, caching, and cryptographic verification, developers can develop more in-depth scripts and projects which can be updated on-the-fly whenever, and wherever, they want.Enhanced FunctionalityPhotons extend the capabilities of the Luminal framework and projects by providing additional features, services, or behaviors. They can handle diverse tasks such as image processing, data manipulation, authentication, logging, and more.Framework IntegrationPhotons seamlessly integrate into any project and make use of its features and components. This integration ensures compatibility and simplifies the usage of common functionalities, such as logging, plugin management, and event handling. Photons can also call the framework in a nested complex way.Customization and ExtensibilityDevelopers can create their own photons, tailor-made to address project-specific requirements, or extend existing photons to modify or enhance their functionality. This customization allows for a flexible and scalable approach to project development.Standardization and ConsistencyAs photons follow a predefined set of conventions and standards, they promote consistency across projects. This standardization ensures that developers can easily understand and work with different photons within the Luminal ecosystem.Collaboration and Shared DevelopmentLeveraging photons encourages collaboration among developers working on Luminal-based projects. They can share and contribute to a growing collection of photons, benefiting from each other's expertise and leveraging existing functionality.Overall, photons provide an organized and extensible approach to project development within the Luminal framework. They enable developers to enhance project functionality, promote modularity and code reuse, and benefit from collaboration and shared development efforts. By utilizing photons, developers can streamline their projects, focus on specific requirements, and maintain a structured and extensible codebase.Creating a PhotonThe following examplePhotonclass is a concrete implementation of theIPhotonabstract base class from the Luminal framework. It represents a simple new program that greets the world when initialized. The photon defines an__init__()method, which is called when a new instance of Photon is created. Inside this method, the program greets the world by printing the greeting message to the console.The photon also defines an async method namedfinalize(). This method overrides the optional finalize method from theIPhotonbase class. The finalize method is intended to be used for cleaning up resources when the plugin or program utilizing thePhotonobject is unloaded. In this implementation, the finalize method simply prints a message indicating that the photon was absorbed, or unloaded, gracefully.fromluminal.interfacesimportIPhotonclassPhoton(IPhoton):def__init__(self:"Photon"):"""Create a simple new program to greet the world."""print("Hello, World!")asyncdeffinalize(self:"Photon")->bool:"""Override the optional program finalizer to cleanup resources."""print("The photon was absorbed gracefully.")This code demonstrates the fundamental usage of theIPhotonbase class and the custom implementation of thePhotonclass. Notably, thePhotonclass doesn't introduce any new attributes or methods beyond what is defined in theIPhotonbase class. Overall, this code showcases the basic implementation of a Luminal photon with a simple greeting functionality. It demonstrates the ability to define custom behavior and cleanup tasks, providing a foundation for building more complex and feature-rich Luminal photons.Loading, Reloading, & Unloading a PhotonThe following code demonstrates the loading, reloading, and unloading of a photon within aProgramclass. It utilizes theLoaderclass from the Luminal framework and relies on asynchronous programming using theasynciomodule.Program Class AttributesTheProgramclass encapsulates the photon and its related operations. It has the followingattributes:|Attribute        |Type     |Scope    |Description ||:----------------|:-------:|:-------:|:-----------||photon|str|Public   |A string representing the path to the photon file to be loaded.||loader|Loader|Public   |Responsible for managing photons which includes functionality such as loading, reloading, and unloading.|Program Class MethodsThe class also defines the followingmethods:|Method           |Scope    |Description ||:----------------|:-------:|:-----------||load|Public   |An asynchronous method that loads a photon by calling theload_photon()method of theLoaderinstance. It then starts the photon instance by calling its start method.||reload|Public   |An asynchronous method that reloads a specified photon instance. It calls thereload_photon()method of theLoaderinstance and then starts the photon instance again.||unload|Public   |An asynchronous method that stops and unloads a specified photon. It calls theunload_photon()method of theLoaderinstance and prints the file's full path.|fromluminal.managersimportLoaderimportasyncioclassProgram:def__init__(self:"Program")->None:"""Create a new program to hold a photon path and photon manager."""self.photon="photon_path.py"self.loader=Loader(logging=True)asyncdefload(self:"Program"):"""Loads a photon and starts its instance."""photon=awaitself.loader.load_photon(self.photon)awaitphoton.start()asyncdefreload(self:"Program"):"""Reloads a specified photon instance or rolls it back if unable."""photon=awaitself.loader.reload_photon(self.photon)awaitphoton.start()asyncdefunload(self:"Program"):"""Stops and unloads a specified photon."""unloaded=awaitself.loader.unload_photon(self.photon)print(unloaded)# Prints the file's full path, a.k.a 'self.photon'.if__name__=="__main__":program=Program()asyncio.run(program.load())asyncio.run(program.reload())asyncio.run(program.unload())In summary, this code demonstrates the basic usage of theLoaderclass toload,reload, andunloada Luminal photon. It initializes theProgramclass with the photon file path and aLoaderinstance. It then asynchronously loads the photon, reloads it, and finally unloads it while printing the file's full path.Loading a Specific ClassIn the following example, theload_photon()function is being called with several arguments:photon_pathThis is the path to the photon module file that will be loaded.photon_baseThis is an optional argument that specifies the base class for the photon modules to be loaded. In this code, the base class isMyClass.other_classesThis is an optional argument that specifies a list of other class names to be loaded from the photon module. In this code,ClassAandClassBwill be loaded.recursiveThis is a boolean flag that indicates whether to search for photon modules recursively under the provided path. In this code, it is set to True, so the function will search for photon modules recursively.Also, theload_photon()function returns alistofHandlerobjects representing the loaded photons, or an empty list if no photons are successfully loaded.photon=self.loader.load_photon(photon_path:str,photon_base:type=MyClass,other_classes:list[str]=['ClassA','ClassB'],recursive:bool=True)Lastly, it's worth noting that theload_photon()function raises aPhotonNotFoundErrorerror if the provided photon path doesn't exist or is a directory.Watching & Atomic Reloading PhotonsThe following code demonstrates how to watch photons for changes using theLoaderclass. It initializes theProgramclass with the directory path where the photons are located and aLoaderinstance. It then asynchronously begins watching the photons and continuously checks for changes to reload them. The program can be stopped by user input, and upon stopping, all photons are unloaded.fromluminal.managersimportLoaderimportasyncioclassProgram:def__init__(self:"Program")->None:"""Create a new program to hold a photon manager and photon paths."""self.photons="photons_directory"self.loader=Loader(logging=True)asyncdefwatch(self):"""Spawns a sentinel, loads photons, and watches for changes to reload."""awaitself.loader.watch_photons(self.photons)asyncdefstop(self):"""Stops the spawned sentinel and begin unloading all photons."""awaitself.loader.stop_watching_photons(halt_threads=True)if__name__=="__main__":program=Program()asyncio.run(program.watch())whileinput("Press any key to exit!")!="":passasyncio.run(program.stop())The code begins by importing the necessary modules:Loaderfromluminal.managers.loaderandasynciofrom standard Python. Next, a class namedProgramis defined. This class represents a program that manages watching photons and handling their reloading. The__init__()method initializes the program by setting the photons attribute to the directory path where the photons are located and creating an instance of theLoaderclass with logging enabled. The watch method is an asynchronous method that spawns a sentinel, loads photons using thewatch_photons()method of theLoaderinstance, and continuously watches for changes to reload the photons.The stop method is an asynchronous method that stops the spawned sentinel and begins unloading all photons using thestop_watching_photons()method of theLoaderinstance withhalt_threads=Trueto ensure all threads are halted during unloading. The program then creates an instance of theProgramclass named program. The watch method of the program object is called usingasyncio.run()to asynchronously start watching the photons.A while loop is used to wait for user input for the program to exit; and will continue until any key is pressed. Finally, the stop method of the program object is called usingasyncio.run()to asynchronously stop the sentinel and unload all photons.Other Tools & FeaturesTracing LoopsThe provided code consists of three parts. The first part includes two classes:LoopTraceandLoopTask. They are used to create a versatile tool for testing and tracing loops. The second part showcases the usage of these classes in an example. The third part defines additional tools and features used in the code.fromluminal.managersimportLoopTask,LoopTraceasyncdefdo_task(some_arg):"""A random function defined as an example."""print(some_arg)defcreate_loop():"""Creates an infinite loop with a trace attached to it for logging."""task=LoopTask(at_iteration=5,coroutine=do_task,some_arg='hello')trace=LoopTrace(tasks=[task],iteration_limit=10)# 0 is infinite iterations.whileTrue:try:awaittrace.evaluate_tasks()exceptStopIteration:# Corresponds to the iteration_limit set above.breakcreate_loop()LoopTrace:TheLoopTraceclass serves as a tool for testing loops, including infinite loops. It can be seamlessly integrated into any codebase. The provided example demonstrates how to create aLoopTraceinstance and evaluate tasks within an infinite loop until the iteration limit is reached.|Attribute            |Type     |Scope    |Description ||:--------------------|:-------:|:-------:|:-----------||tasks|list|Public   |A list of tasks to be evaluated at specific iterations.||tasks_with_keys|dict|Public   |A dictionary mapping tasks to their iterations.||iteration_limit|int|Public   |The maximum number of iterations.||current_iteration|int|Public   |The current iteration being evaluated. RaisesKeyErrorif a task that already exists is added, andStopIterationif the maximum iteration limit is reached.|LoopTask:This class wraps a coroutine and its arguments to be executed at a specific iteration within a loop.|Attribute            |Type     |Scope    |Description ||:--------------------|:-------:|:-------:|:-----------||_at_iteration|int|Internal  |The iteration at which to raise aStopIterationexception to break.|Traced Thread ManagementTheThreadManagerclass is designed to manage and control the execution of multiple threads in a program. It maintains a list of running and requested threads, a flag to stop all threads gracefully, and settings for running threads based on given limits.ThreadManager AttributesTheThreadManagerhas the following attributes:|Attribute            |Type     |Scope    |Description ||:--------------------|:-------:|:-------:|:-----------||_manager_uid|str|Internal |A unique identifier for each instance of theThreadManagerclass.||_running_threads|dict|Internal |A dictionary of currently running threads in the program, with each key representing a thread ID and each value being its respectiveTracedThreadobject.||_requested_threads|list|Internal |A list of all threads waiting to be executed, represented asTracedThreadobjects.||_flag_request|bool|Internal |A flag used to indicate the user's request to stop all threads in the program.||_currently_watching|bool|Internal |A flag used to indicate if the program should continuously watch and execute all threads based on the given thread limit.||_currently_running|bool|Internal |A flag used to indicate if the program should run all threads based on the given thread limit only once.||thread_limit|int|Public   |The maximum number of threads that can be simultaneously running in the program.|ThreadManager MethodsTheThreadManagerclass also provides methods to manage threads, such as:|Method           |Scope    |Description ||:----------------|:-------:|:-----------||append_thread|Public   |Appends a new thread to the list of requested threads.||run|Public   |Starts executing the requested threads, taking into account the given thread limit.||stop|Public   |Stops all currently running or requested threads gracefully.|Additionally, the code provided in this example includes a function calculate, which is an example of a truly random function with no intrinsic value. This function uses a loop and sleeps for1second in each iteration. It continuously performs calculations on the given values ofxandyand prints the updated values.fromluminal.managersimportTracedThread,ThreadManagerimporttimedefcalculate(x,y):"""A truly random function with no intrinsic value."""whileTrue:x=x*y/2y=x*y/3time.sleep(1)print(f"{x},{y}")returncalculate(x,y)defstart_traced_manager():"""Create a thread manager, append a task, and begin a traced cycle."""manager=ThreadManager()manager.append_thread(function=calculate,args=(10,20),kwargs={})manager.run()manager.stop()defstart_traced_thread():"""Starts an infinite loop function using a traced thread."""task=TracedThread(target=calculate,args=(10,20),kwargs={})task.start()start_traced_manager()start_traced_thread()The functionsstart_traced_manager()andstart_traced_thread()demonstrate different approaches to using theThreadManagerclass. Thestart_traced_manager()function creates an instance ofThreadManager, appends a task (using thecalculate(x,y)function withx=10andy=20), and then runs the manager. The manager will start executing the task while managing the given thread limit. Finally, the manager is stopped gracefully.On the other hand,start_traced_thread()directly starts an infinite loop function (calculate) using aTracedThread. This demonstrates the use of a traced thread without the involvement of theThreadManagerclass.Overall, this code provides flexibility for managing and controlling the execution of multiple threads in a program, allowing for efficient utilization of system resources and handling of thread limits.Sentinel & UtilsThe given code is a Python program that creates and spawns aSentinelobject. TheSentinelclass is a system watching mechanism used for monitoring files or collecting and cleaning garbage.fromluminal.toolsimportSentinelimporttimeclassProgram:def__init__(self)->None:"""Create a new program with a logger and spawning functions."""self._logger=Logger(__name__)defspawn_sentinel(self:"Program"):"""Create a sentinel and allow it to clean the system."""self._logger.note("Spawning a sentinel...")sentinel=Sentinel()sentinel.authorized=Truesentinel.start()time.sleep(1)# Sleep the thread for cache cleanup.# Note: If whatever application you're runnning stays active# for more than 1 second, then the sleep call is optional.if__name__=="__main__":program=Program()program.spawn_sentinel()TheProgramclass in this code has an__init__()method that initializes aLogger; and thespawn_sentinel()method is responsible for creating and starting aSentinelobject.In thespawn_sentinel()method, a logger message is printed to indicate that a sentinel is being spawned. An instance ofSentinelis created and assigned to the variable sentinel. The authorized attribute of the sentinel object is set toTrueto allow the sentinel to actually monitor the system, otherwise, it would standby idle. Next, the start method of the sentinel object is called to initialize its monitoring process.Atime.sleep()call is made with a duration of1second, which delays the program execution for cache cleanup. This is an optional step and is only necessary if the application being run remains activefor less than1second. Finally, in theif __name__ == "__main__":block, an instance of theProgramclass is created and assigned to the variable program. Thespawn_sentinel()method of the program object is then invoked to start the sentinel and have it monitor the system.💡 Conclusion:In today's fast-paced software development landscape, it's becoming increasingly important for developers to streamline and optimize their projects to keep up with the growing demands of users. Luminal offers developers the perfect solution to achieve this effortlessly by creating dynamic and modular plugins, a.k.aPhotons.This library has been meticulously created based on best practices and is composed of 100% pure Python code with no dependencies, except for the unit testing package namedcoverage. The library's asynchronous and multi-threaded capabilities offer efficient utilization of system resources, while atomic reloading and monitoring capabilities allow hot reloading of code to improve performance, eliminate downtime, and debug errors faster. Furthermore, Luminal's small footprint technology makes it ideal for various project types and sizes. Luminal offers reliability and efficiency, with comprehensive documentation covering private methods, metaclasses, utilities, and public-facing functions, making it the perfect solution for streamlining your projects and optimizing resources.The importance of this library cannot be understated, as it provides developers with a way to customize their solutions, improve software flexibility, and optimize required resources to scale their projects more efficiently and securely.🧠 License:Copyright © 2023 Jason DrawdyAll rights reserved.The MIT License (MIT)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.Except as contained in this notice, the name of the above copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.Built with Autumn (Jason's AI) — 2023-07-27 @ 03:58:15