-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
989763e
commit d21d574
Showing
1 changed file
with
172 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,110 +1,219 @@ | ||
| # Python apps | ||
| # Python Apps | ||
|
|
||
| - [Python apps](#python-apps) | ||
| - [Description](#description) | ||
| - [Available programs](#available-programs) | ||
| [](LICENSE) | ||
|  | ||
|
|
||
| [](https://python-poetry.org/) | ||
| [](https://github.com/ellerbrock/open-source-badges/) | ||
| [](https://github.com/JakubKorytko/python-apps/actions/workflows/super-linter.yml) | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| - [Python Apps](#python-apps) | ||
| - [Table of Contents](#table-of-contents) | ||
| - [Introduction](#introduction) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Installation](#installation) | ||
| - [Usage](#usage) | ||
| - [Menu](#menu) | ||
| - [Categories](#categories) | ||
| - [Programs generated data](#programs-generated-data) | ||
| - [Extending the project](#extending-the-project) | ||
| - [Adding new categories](#adding-new-categories) | ||
| - [Adding new apps](#adding-new-apps) | ||
| - [Building the application](#building-the-application) | ||
| - [Troubleshooting](#troubleshooting) | ||
| - [Missing dependencies](#missing-dependencies) | ||
| - [Contributing](#contributing) | ||
| - [Contact](#contact) | ||
| - [License](#license) | ||
|
|
||
| ## Description | ||
| ## Introduction | ||
|
|
||
| "python-apps" is a console app with a menu from which you can choose many programs coded in Python, including graphical ones. The program scans the "apps" directory (which can be changed in the "main.py" file) and finds programs based on the following rules: | ||
| This may feel like just another collection of random Python applications made by a beginner, | ||
| but it is not. | ||
|
|
||
| - Folders marked with "[C]" are categories that can contain programs and can be entered in the menu | ||
| - Folders marked with "[P]" are programs that can be run from the menu. The program will search for a "main.py" file inside and attempt to run it. | ||
| (Note that folders cannot have both markers at the same time.) | ||
| It is an extensible yet simple app that allows you to run apps from a menu. | ||
| The apps are divided into categories and can be nested. | ||
| The app is designed to be easily extensible, | ||
| so you can add your own apps and categories because the app will look for them | ||
| in the [pyap_apps](./pyap_apps/) directory so no real programming knowledge is required. | ||
|
|
||
| "Category" folders can contain other "categories," "programs," and a "desc.txt" file. The "desc.txt" file is read when the user selects the corresponding option in the menu. It can contain a description of the category. | ||
| Thanks to this project, you can easily create your own collection of applications and share it with others. | ||
| For more information, see [extending the project](#extending-the-project). | ||
|
|
||
| "Program" folders can contain a "desc.txt" file, program files and folders, and a "main.py" file. Without a "main.py" file, the program cannot be run from the console menu. The "desc.txt" file is read when the user selects the corresponding option in the menu. It can contain a description of the program. | ||
| ## Prerequisites | ||
|
|
||
| ## Available programs | ||
| Before you begin, make sure you have the following prerequisites installed on your system: | ||
|
|
||
| The "python-apps" program comes with many apps included: | ||
| - [Python 3.11.4 or later](https://www.python.org/downloads/) | ||
| - [Poetry 1.7.1 or later](https://python-poetry.org/docs/#installation) | ||
|
|
||
| **airQuality** | ||
| This app displays current air quality in Cracow and nearby cities | ||
| **imagesFilter** | ||
| This app takes array of images as the input and displays them with options to add filters | ||
| **anagram** | ||
| This program finds anagrams in a list of words. | ||
| **line** | ||
| The program checks if a point belongs to a straight line | ||
| **palindrome** | ||
| This program checks if a phrase is a palindrome | ||
| **segment** | ||
| This is a module with functions for calculating the distance of a point from a segment by the equation of a line | ||
| **sortLetters** | ||
| This program will sort letters from given word or phase | ||
| **triangle** | ||
| This program will check if you can create triangle from the given sides | ||
| **average** | ||
| This program calculates the grade point average based on a "grades.txt" file in the directory or manual input. The "grades.txt" file must contain only numbers from 1 to 6 separated by commas and be in the program directory. | ||
| ## Installation | ||
|
|
||
| ... and many more! | ||
| 1. Clone this repository to your local machine using Git, | ||
| or download the ZIP file and extract it to a directory of your choice: | ||
|
|
||
| You can add new programs and categories and change existing ones. | ||
| ```bash | ||
| git clone https://github.com/JakubKorytko/python-apps.git | ||
| ``` | ||
|
|
||
| 1. Change to the project directory: | ||
|
|
||
| ## Prerequisites | ||
| Before you can run the "python-apps" program, you will need to have the following installed on your system: | ||
| ```bash | ||
| cd python-apps | ||
| ``` | ||
|
|
||
| - [Python 3](https://www.python.org/downloads/) | ||
| - [pip (Python package manager)](https://pip.pypa.io/en/stable/installation/) | ||
| 1. Run the following command to install the required dependencies: | ||
|
|
||
| To check if you have Python 3 installed, open your terminal and run the following command: | ||
| ```bash | ||
| poetry install | ||
| ``` | ||
|
|
||
| You can now run the project by executing the following command: | ||
|
|
||
| ```bash | ||
| python3 --version | ||
| poetry run python-apps | ||
| ``` | ||
|
|
||
| To check if you have pip installed, run the following command: | ||
| ## Usage | ||
|
|
||
| ```bash | ||
| pip --version | ||
| ``` | ||
| The application has an intuitive menu that allows you to navigate through the applications and categories, | ||
| that are displayed when you run the application. | ||
|
|
||
| ## Installation | ||
| To install "python-apps", follow these steps: | ||
| ### Menu | ||
|
|
||
| The menu displays categories and apps according to the | ||
| [pyap_apps](./pyap_apps/) directory structure. | ||
|
|
||
| The options are numbered and you can select them by typing the corresponding number. | ||
|
|
||
| Applications can be identified by the `[P]` (or `[p]`) at the end of their name, | ||
| and categories by the `[C]` (or `[c]`) at the end of their name. | ||
| Applications will also have a yellow font color, and categories will have a blue font color. | ||
|
|
||
| You can get the description (if `desc.txt` exists, | ||
| see [extending the project](#extending-the-project)) of the selected application or category | ||
| by typing its number followed by `?`. | ||
|
|
||
| ### Categories | ||
|
|
||
| The application has a built-in categories (with applications) which are located in the [pyap_apps](./pyap_apps/) directory: | ||
|
|
||
| - [console_apps[C]](./pyap_apps/console_apps[C]/) | ||
| - [matura_tasks[C]](./pyap_apps/matura_tasks[C]/) | ||
| - [tkinter_apps[C]](./pyap_apps/tkinter_apps[C]/) | ||
|
|
||
| ### Programs generated data | ||
|
|
||
| When one of the applications generates data, it is stored in the application directory. | ||
|
|
||
| For example, if you are running the `pyap_apps/(...)/App[P]/main.py` app, | ||
| and the app generates data, it will be stored in the `pyap_apps/(...)/App[P]` directory. | ||
| If the applications uses a subdirectory to store the data, | ||
| it will be stored in the corresponding subdirectory of the `pyap_apps/(...)/App[P]` directory. | ||
|
|
||
| `(...)` represents the category directories as they can be nested. | ||
|
|
||
| ## Extending the project | ||
|
|
||
| 1. Clone the repository to your local machine using the following command: | ||
| App categories and apps are determined by the directories in the [pyap_apps](./pyap_apps/) directory. | ||
| A directory can be either a category or an application, but not both. | ||
| You can add new categories and apps by creating new directories in the [pyap_apps](./pyap_apps/) directory. | ||
|
|
||
| The application will look for `pyap_apps` in the following locations: | ||
|
|
||
| 1. First, in the parent directory of the [\_\_main\_\_.py](./python_apps/__main__.py) file | ||
| 2. If not found, in the [\_\_main\_\_.py](./python_apps/__main__.py) file directory | ||
|
|
||
| You can rename or move the [pyap_apps](./pyap_apps/) directory to another location, | ||
| but you must specify the new location in the [\_\_main\_\_.py](./python_apps/__main__.py) file. | ||
| If you intend to build the application, you will need to update the [pyproject.toml](./pyproject.toml) file. | ||
|
|
||
| ### Adding new categories | ||
|
|
||
| Category directories must have a `[C]` (or `[c]`) at the end of their name. | ||
| For example, `pyap_apps/Category[C]` is a valid category directory, | ||
| but `pyap_apps/Category` is not and will be ignored by the application. | ||
|
|
||
| Categories can contain other categories and applications. | ||
|
|
||
| You can add a `desc.txt` file to the category directory | ||
| to provide a description of the category. | ||
|
|
||
| ### Adding new apps | ||
|
|
||
| Application directories must contain a `[P]` (or `[p]`) at the end of their name. | ||
| For example, `pyap_apps/App[P]` is a valid application directory, | ||
| but `pyap_apps/App` is not and will be ignored by the application. | ||
|
|
||
| You can put a `desc.txt` file in the app directory | ||
| to provide a description of the application. | ||
|
|
||
| The application will look for a `main.py` file in the app directory | ||
| and execute it if found. | ||
|
|
||
| Each app is executed in a separate subprocess and so it must be a standalone program. | ||
| This makes the app more secure, and less likely to crash the main app or other apps. | ||
|
|
||
| If your application requires additional dependencies, | ||
| you can add them to the [pyproject.toml](./pyproject.toml) file manually, | ||
| or by running the following command: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/JakubKorytko/python-apps.git | ||
| poetry add <dependency> | ||
| ``` | ||
|
|
||
| 2. Navigate to the main app directory using the command-line interface. | ||
| ## Building the application | ||
|
|
||
| To build the application, run the following command: | ||
|
|
||
| ```bash | ||
| cd python-apps | ||
| poetry build | ||
| ``` | ||
|
|
||
| 3. Install the required packages by running the following command: | ||
| The built application will be located in the `dist` directory. | ||
| It should contain `.whl` and `.tar.gz` files. You can install the application by running the following command: | ||
|
|
||
| ```bash | ||
| pip install -r requirements.txt | ||
| pip install <path-to-whl-or-tar.gz-file> | ||
| ``` | ||
|
|
||
| This command will install all the required packages that are listed in the "requirements.txt" file. | ||
| ## Troubleshooting | ||
|
|
||
| Once you have installed the required packages, you can run the program by navigating to the main app directory and running the following command: | ||
| ### Missing dependencies | ||
|
|
||
| ```bash | ||
| python main.py | ||
| ``` | ||
| Running the `poetry install` command should be sufficient in most cases, | ||
| but some dependencies may need to be installed manually. | ||
| If any of the applications fail to run due to missing dependencies, | ||
| make sure that: | ||
|
|
||
| ## Usage | ||
| - They are listed in the [pyproject.toml](./pyproject.toml) file | ||
| - You have run the `poetry install` command | ||
| - If the above steps did not help, try installing the dependencies manually | ||
| with a [pip](https://pip.pypa.io/en/stable/) command: | ||
|
|
||
| To use the "python-apps" program, run the following command: | ||
| ```bash | ||
| pip install <dependency> | ||
| ``` | ||
|
|
||
| ```bash | ||
| python main.py | ||
| ``` | ||
| - If the problem persists, search the web to see if there are any additional steps required | ||
| to install the dependency or if it is compatible with your system. | ||
| Some dependencies may require you to install additional system packages. | ||
| `Tkinter` is one such example on the Linux operating system. | ||
|
|
||
| - If you are unable to find a solution, feel free to open an issue. | ||
|
|
||
| ## Contributing | ||
|
|
||
| If you find issues or have suggestions for improvements, | ||
| feel free to open an issue or submit a pull request. | ||
| Contributions are welcome! | ||
|
|
||
| ## Contact | ||
|
|
||
| This will start the program and display the main menu. From there, you can navigate the menu and run the programs. | ||
| If you have any questions, feel free to contact me at <jakub@korytko.me>. | ||
|
|
||
| ## License | ||
|
|
||
| This project uses the following license: [MIT](https://choosealicense.com/licenses/mit/) | ||
| This project is released under the MIT License. See the [LICENSE](LICENSE) file for details. |