Package: pyggester
Pyggester - dynamic/static python analysis📘 Aboutpyggester - (python + suggester) functions as both a dynamic and static analyzer. Its primary purpose lies in offering suggestions to enhance the efficiency of Python code by addressing suboptimal usage of data structures.⭐ FeaturesPyggester offers a pretty decent cli interface for its functionalities. The cli is built on top oftyperExecution command:pyggestoutput:_____
_____________  ________ _______ ______________  /_____________
___  __ \_  / / /_  __ `/_  __ `/  _ \_  ___/  __/  _ \_  ___/
__  /_/ /  /_/ /_  /_/ /_  /_/ //  __/(__  )/ /_ /  __/  /
_  .___/_\__, / _\__, / _\__, / \___//____/ \__/ \___//_/
/_/     /____/  /____/  /____/


Usage: pyggest [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                                                                      │
│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                               │
│ --help                        Show this message and exit.                                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ static                 Perform static analysis using PyggestStatic.                                                                          │
│ transform              Perform dynamic transformation using PyggesterDynamic.                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯The pyggester CLI presents two distinct features:Static Analysis: This feature comprehensively examines your code without executing it, providing insightful insights into its structure and potential improvements.Execution command[!NOTE]
The 'static' subcommand exists, but has no functionalities implemented, because we already have good static analyzers(pylint, ruff, flake8). In future iterations, should we identify suggestions that can be established through static analysis, we will incorporate them into this feature.pyggeststaticDynamic/Automatic Transformation: This feature adds extra code to your python files to analyze your data structures at runtime. Your original code stays the same; it won't be changed. A new file is created that's just like the original but with additional code. This works for both single files and whole directories(full project structures).Execution commandpyggesttransform[!INFO]
pyggester offers built-in documentation for detailed usagepyggesttransform--helppyggeststatic--help#NOT IMPLEMENTED🔧 InstallationUsing PipYou can easily install the Python library using pip. Open your terminal and run the following command:pipinstallpyggesterCloning the GitHub RepositoryClone the Repository:Open your terminal and run the following command to clone the GitHub repository to your local machine:gitclonegit@github.com:ValdonVitija/pyggester.gitNavigate to the Repository:Change your working directory to the cloned repository:cdpyggesterInstall pyggester as a pacakge locally:[!IMPORTANT]
Consider doing this within a virtual environment (venv) if possible.pipinstall.Usage (Step-by-Step)Single File UsageLets suppose you have a single python file that you want to dynamically analyze(run-time analysis)1. PreparationBefore code transformation with pyggester:(venv)root@user:~/my_app>ls
app.pyContent of app.py:defsum_of_integers(integer_list):total=sum(integer_list)returntotalmy_list=[1,2,3,4,5]print(sum_of_integers(my_list))2. Transformation[!IMPORTANT]Make sure you're in a virtual environment with pyggester installed before going to the next step.(venv)root@devs04:~/my_app>pyggesttransformapp.py
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│Filetransformedsuccessfully!│
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯3. Post-Transformation(venv)root@devs04:~/my_app>ls
app.pyapp_transformed.pyContent of app_transformed.py:frompyggester.observable_collectorimportOBSERVABLE_COLLECTORfrompyggester.observablesimportObservableNumpyArray,ObservableNamedTuple,ObservableSet,ObservablePandasDataFrame,ObservableList,ObservableDict,ObservableTupledefsum_of_integers(integer_list):total=sum(integer_list)returntotalmy_list=ObservableList([1,2,3,4,5])OBSERVABLE_COLLECTOR.append(my_list)print(sum_of_integers(my_list))forobservableinOBSERVABLE_COLLECTOR:observable.run()[!IMPORTANT]
We now have a new file, automatically created, that mirrors the original file. This new file includes all the contents of the original, plus extra code for analyzing your code during runtime. Instead of running the original 'app.py', you should now run 'app_transformed.py'. Rest assured, everything from 'app.py' is retained in 'app_transformed.py'.4. Running the Transformed Code(venv)root@devs04:~/my_app>python3app_transformed.py15╭────────────────────────────────────────────────────────────────────────────╮
│10|Suggestions(/root/my_app/app_transformed.py):│
│[*]Considerusinganarray.arrayinsteadofalist,foroptimal│
│memoryconsumption│
│[*]Considerusingasetinsteadofalist,becauseofuniqueelements│
╰────────────────────────────────────────────────────────────────────────────╯Directory UsageLets suppose you have a python project(directory/repo) that you want to dynamically analyze(run-time analysis)1. PreparationBefore code transformation with pyggester:(venv)root@devs04:~/python_demo/app_dir>ls
__pycache__app.pytemperature.pyweather.pyContent of app.py:importweatherimporttemperaturedefmain():city=input('Enter a city name: ')weather_condition=weather.get_weather(city)avg_temp=temperature.get_average_temperature()print(f'Weather in{city}:{weather_condition}')print(f'Average temperature:{avg_temp}degrees Celsius')main()Content of temperature.py:temperatures=list([20,22,15,18,20,21,22,22,18,17,20])defget_average_temperature():returnsum(temperatures)/len(temperatures)Content of weather.py:weather_conditions=['Sunny','Rainy','Cloudy','Windy','Sunny','Cloudy']defget_weather(city):returnweather_conditions.pop()2. Transformation[!IMPORTANT]Make sure you're in a virtual environment with pyggester installed before going to the next step.(venv)root@devs04:~/python_demo>pyggesttransformapp_dir/
Enterthenameofthemainfile:app.py
╭──────────────────────────────────────────────────────────────────────────╮
│Directorytransformedsuccessfully!│
╰──────────────────────────────────────────────────────────────────────────╯[!IMPORTANT]
When a directory or project is specified as an argument, pyggester prompts us to specify the main file of our project. This file should be the entry point of your project, indicated by its file name.3. Post-Transformation(venv)root@devs04:~/python_demo>ls
app_dirapp_dir_transformedContent of app_dir_transformed/:(venv)root@devs04:~/python_demo/app_dir_transformed>lsapp.pytemperature.pyweather.pyContent of app.py:frompyggester.observable_collectorimportOBSERVABLE_COLLECTORfrompyggester.observablesimportObservableNumpyArray,ObservableList,ObservablePandasDataFrame,ObservableNamedTuple,ObservableSet,ObservableDict,ObservableTupleimportweatherimporttemperaturedefmain():city=input('Enter a city name: ')weather_condition=weather.get_weather(city)avg_temp=temperature.get_average_temperature()print(f'Weather in{city}:{weather_condition}')print(f'Average temperature:{avg_temp}degrees Celsius')main()forobservableinOBSERVABLE_COLLECTOR:observable.run()Content of temperature.py:frompyggester.observable_collectorimportOBSERVABLE_COLLECTORfrompyggester.observablesimportObservableNumpyArray,ObservableList,ObservablePandasDataFrame,ObservableNamedTuple,ObservableSet,ObservableDict,ObservableTupletemperatures=ObservableList(list([20,22,15,18,20,21,22,22,18,17,20]))OBSERVABLE_COLLECTOR.append(temperatures)defget_average_temperature():returnsum(temperatures)/len(temperatures)Content of weather.py:frompyggester.observable_collectorimportOBSERVABLE_COLLECTORfrompyggester.observablesimportObservableNumpyArray,ObservableList,ObservablePandasDataFrame,ObservableNamedTuple,ObservableSet,ObservableDict,ObservableTupleweather_conditions=ObservableList(['Sunny','Rainy','Cloudy','Windy','Sunny','Cloudy'])OBSERVABLE_COLLECTOR.append(weather_conditions)defget_weather(city):returnweather_conditions.pop()[!IMPORTANT]
We now have a new directory, automatically created, that mirrors the original directory. This new directory includes all the contents of the original, plus extra code for analyzing your code during runtime. Instead of running the original 'app.py', you should now run 'app.py' that resides inside 'app_dir_transformed/'. Rest assured, everything from 'app_dir' is retained in 'app_dir_transformed/'.4. Running the Transformed Code(venv)root@devs04:~/python_demo/app_dir_transformed>python3app.py
Enteracityname:Pristina
WeatherinPristina:Cloudy
Averagetemperature:19.545454545454547degreesCelsius
╭─────────────────────────────────────────────────────────────────────────────────────╮
│3|Suggestions(/root/python_demo/app_dir_transformed/temperature.py):│
│[*]Considerusinganarray.arrayinsteadofalist,foroptimalmemory│
│consumption│
╰─────────────────────────────────────────────────────────────────────────────────────╯📁 Directory Structure.
├──LICENSE
├──README.md#main readme file. The one you are currently reading.├──VERSION#version of pyggester├──contributing.md
├──pyggester# directory containing the full source code of pyggester│├──__init__.py
│├──cli.py#defines the typer cli structure(command & options)│├──command_handlers.py#Handles subcommands and every option variation per subcommand.│├──data#data/config files related to pyggester.││└──help_files#build in help files for the pyggester cli││├──__init__.py
││├──transform_helper.md#detailed built-in documentation for the transform subcommand of pyggest││└──static_helper.md#detailed built-in documentation for the static subcommand of pyggest│├──helpers.py#helper functions to be used by other modules│├──main.py#The entry point of pyggest execution. Initializes the typer cli app and prints the ascii logo of pyggester│├──message_handler.py#Manages how the collected messages will be printed to the user.│├──module_importer.py#Contains the mechanism to automatically import observables│├──observable_collector.py#Contains the list that will be used to collect all observables.│├──observable_transformations.py#Contains the mechanism that will automatically add code that collects observables and glues together all ast modules│├──observables.py#Contains all the defined observables(enhanced version of python collections)│├──pyggester.py#The 'engine' of pyggester. This module glues everything together│├──text_formatters.py#Contains text formatters, to beautify text in stdout.│└──wrappers.py#Contains the mechanism that wrap each observable.├──pyggester_abstract_execution_flow.png
├──pyggester_logo.png
├──pytest.ini#pytest config file├──requirements.txt#Every pyggester dependecy resides here├──setup.py#Creates the pyggester pacakge and defines pyggest as the entry point command to execute pyggester└──tests├──__init__.py├──test_cli.py├──test_command_handlers.py├──test_file.py├──test_file_transformed.py├──test_helpers.py├──test_main.py├──test_message_handler.py├──test_module_importer.py├──test_observable_transformations.py├──test_observables.py├──test_pyggester.py└──test_wrappers.pyAbstract Execution FlowThe following flow diagram illustrates key components of Pyggester and provides a comprehensive overview of the execution sequence.👥 ContributionTo contribute to this project, please refer to the comprehensivecontribution guidefor detailed instructions and best practices.©️ LicenseMIT LicenseCopyright (c) 2023 ValdonVitijaaPermission 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.