# PLAN-TOOLS
[](https://github.com/Myoldmopar/PLAN-Tools/actions/workflows/flake8.yml)
[](https://github.com/Myoldmopar/PLAN-Tools/actions/workflows/test.yml)
[](https://coveralls.io/github/Myoldmopar/PLAN-Tools?branch=main)
[](https://github.com/Myoldmopar/PLAN-Tools/actions/workflows/release.yml)
[](https://plan-tools.readthedocs.io/en/latest/?badge=latest)
Tooling to help with PLAN: Pip Links And Nonsense
## Introduction
This library is a very lightweight set of helpers to improve the user-friendliness of entry points installed with Pip.
There are other packages that help do some of this, but I struggled to get them configured exactly how I wanted, which led to this new package.
This specifically fits my Python package structure and installation needs, and may not fit anyone else's, and that's OK.
Packages that use this library should fit the following pattern:
- Let's assume the package has these attributes:
- Setup name: "cool_python_stuff" -- this is the name on PyPi, and the string that you Pip install
- Package directory name: "cool" -- this is the source directory once Pip installed, and what you import in your Python
- A Python function with no arguments called `gui_function()` declared in a file located at `cool/gui.py`
- The `setup.py` file should declare a `setup()` function call from the `setuptools` library
- Entry points should be declared using the `setup(entry_points={'gui_scripts': ['cool_gui=cool.gui:gui_function']})` argument form
- The `console_scripts` key is also fine here, but this library is more likely useful for GUI applications
- Icons should be placed in the library, ideally for all platforms, and should be named as the following:
- `cool/icon.png` - this will be used on Linux systems
- `cool/icon.ico` - this will be used on Windows systems
- `cool/icon.icns` - this will be used on MacOS systems
- The GUI code itself should set the titlebar icon programmatically, although this won't address the taskbar icon.
## Background and Problem Statement
OK, so `cool_python_stuff` is a Python library with some functionality exposed through an executable interface.
Pip provided executable entry points and placed them in the Python environment.
The final location of these executables is different on each platform, and also depends on whether it is a "user" or "global" install.
How do you best make use of this library and these entry points?
- Of course, you'll need to have Python installed, so you follow any directions [on Python's website](https://www.python.org/).
- In general, you'll also get the Pip package management tool, but if not, then you'll need to get that as well.
- You then Pip install this cool library, which:
- downloads the source and dependencies,
- places it in the current Python environment directory structure,
- generates executable shims for each entry point,
- and places them in the current Python environment directory structure as well.
Depending on the platform and configuration, the executable entry points _may_ be available directly from the shell, but it depends.
The Pip install process will also not create any shortcuts on the desktop or start menu, so the executables are not easily accessible.
That's where this library comes in to help.
## Usage
This helper library is "used" by both the package creator **and** the end using client.
The package manager includes this helper library as a dependency, and creates an executable entry point whose purpose is to call functions in the helper code.
Once the `cool_python_stuff` package is pip installed, the client runs this extra configuration step, which will polish up the installation.
### Developer Responsibility
- Import this library: `from plan_tools import EntryPoint`
- Create a new function `def gui_configure()`
- Inside this function, create a new `EntryPoint` instance for each `entry_point` that should get configured
- The only required EntryPoint argument is the name of the binary, which is the name declared in the `gui_scripts` string spec
- There are several optional arguments which can be found in the full library documentation.
- The `gui_configure` function can take command line arguments as desired to provide custom functionality, such as not producing certain icons.
- The configuration function could also be a GUI itself that allows users to select options before running.
- Either way, the responsibility of documenting this belongs with the package manager.
- Once instantiated and set up properly, the EntryPoint instances have a `run()` method that should be called to actually take action.
- This new `gui_configure` function should be declared as an entry point in the package `setup()` call with a name like `{package_name}_configure`
In addition to setting up this nice launch process, there is more polishing that can be done to enhance the user experience.
When these links are executed, and the Pip installed executable opens, the taskbar icon will just be the Python logo.
This is due to how Pip prepares these executable shims, and it is difficult to figure out how to correctly apply a taskbar icon.
This library provides a worker function that should address this problem.
In the GUI code, (Tkinter, etc.), simply import this library (`from plan_tools.runtime import fixup_taskbar_icon_on_windows`),
and then call that function with a program name (`fixup_taskbar_icon_on_windows('This Cool GUI')`).
The taskbar should now show the same icon that was registered as the program icon using the GUI library.
### Testing
Steps to Test:
- Note which Python executable is being used
- If you are running a virtual environment, you should activate the environment or be ready to use full paths to the binaries inside the virtual environment
- Pip install the test project `pip install plan_tools_test`
- The folder name that Pip uses to place the executable shims is "Scripts" on Windows and "bin" on Mac/Linux, we'll say `{bin}` for now.
- You should be able to test run the test executable if desired:
- If your Python Scripts folder is on PATH, you can run it directly: `plan_tools_test_run`
- If not, you may need to provide the path: `{path/to/venv}/{bin}/plan_tools_test_run`
- Next run the configuration executable:
- If your Python Scripts folder is on PATH, you can run it directly: `plan_tools_test_configure`
- If not, you may need to provide the path: `{path/to/venv}/{bin}/plan_tools_test_configure`
- The outcome depends on the operating system:
- On Windows, by default this should add a new desktop icon for the test package and also a start menu entry for it
- On Linux, specifically Ubuntu (Gnome Shell), you should now be able to open the applications browser and search for Plan, and find the test executable
- On Mac, unfortunately, we don't yet support generating an .app bundle, but that should come soon, in which case the application could be found in the Spotlight
These tests have been completed:
- Windows Virtual Environment:
- OS: Windows
- Python Install Location: C:\Python38
- Python Environment: venv
- Virtual Environment Location: C:\tmp\venv
- Desktop Links
Raw data
{
"_id": null,
"home_page": "https://github.com/Myoldmopar/PlanTools",
"name": "PLAN-Tools",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "energyplus",
"author": "Edwin Lee, for NREL, for United States Department of Energy",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/44/02/2afd83287e71fd5c645f4f1cfacc2cca40f485ad5898cb95e686aae839eb/PLAN-Tools-0.6.tar.gz",
"platform": null,
"description": "# PLAN-TOOLS\n\n[](https://github.com/Myoldmopar/PLAN-Tools/actions/workflows/flake8.yml)\n[](https://github.com/Myoldmopar/PLAN-Tools/actions/workflows/test.yml)\n[](https://coveralls.io/github/Myoldmopar/PLAN-Tools?branch=main)\n[](https://github.com/Myoldmopar/PLAN-Tools/actions/workflows/release.yml)\n[](https://plan-tools.readthedocs.io/en/latest/?badge=latest)\n\nTooling to help with PLAN: Pip Links And Nonsense\n\n## Introduction\n\nThis library is a very lightweight set of helpers to improve the user-friendliness of entry points installed with Pip.\nThere are other packages that help do some of this, but I struggled to get them configured exactly how I wanted, which led to this new package.\nThis specifically fits my Python package structure and installation needs, and may not fit anyone else's, and that's OK.\nPackages that use this library should fit the following pattern:\n\n - Let's assume the package has these attributes:\n - Setup name: \"cool_python_stuff\" -- this is the name on PyPi, and the string that you Pip install\n - Package directory name: \"cool\" -- this is the source directory once Pip installed, and what you import in your Python\n - A Python function with no arguments called `gui_function()` declared in a file located at `cool/gui.py`\n - The `setup.py` file should declare a `setup()` function call from the `setuptools` library\n - Entry points should be declared using the `setup(entry_points={'gui_scripts': ['cool_gui=cool.gui:gui_function']})` argument form\n - The `console_scripts` key is also fine here, but this library is more likely useful for GUI applications \n - Icons should be placed in the library, ideally for all platforms, and should be named as the following:\n - `cool/icon.png` - this will be used on Linux systems\n - `cool/icon.ico` - this will be used on Windows systems\n - `cool/icon.icns` - this will be used on MacOS systems\n - The GUI code itself should set the titlebar icon programmatically, although this won't address the taskbar icon. \n\n## Background and Problem Statement\n\nOK, so `cool_python_stuff` is a Python library with some functionality exposed through an executable interface.\nPip provided executable entry points and placed them in the Python environment.\nThe final location of these executables is different on each platform, and also depends on whether it is a \"user\" or \"global\" install.\n\nHow do you best make use of this library and these entry points?\n\n- Of course, you'll need to have Python installed, so you follow any directions [on Python's website](https://www.python.org/).\n- In general, you'll also get the Pip package management tool, but if not, then you'll need to get that as well.\n- You then Pip install this cool library, which:\n - downloads the source and dependencies,\n - places it in the current Python environment directory structure,\n - generates executable shims for each entry point,\n - and places them in the current Python environment directory structure as well.\n\nDepending on the platform and configuration, the executable entry points _may_ be available directly from the shell, but it depends.\nThe Pip install process will also not create any shortcuts on the desktop or start menu, so the executables are not easily accessible.\n\nThat's where this library comes in to help.\n\n## Usage\n\nThis helper library is \"used\" by both the package creator **and** the end using client.\nThe package manager includes this helper library as a dependency, and creates an executable entry point whose purpose is to call functions in the helper code.\nOnce the `cool_python_stuff` package is pip installed, the client runs this extra configuration step, which will polish up the installation.\n\n### Developer Responsibility\n\n- Import this library: `from plan_tools import EntryPoint`\n- Create a new function `def gui_configure()`\n- Inside this function, create a new `EntryPoint` instance for each `entry_point` that should get configured\n- The only required EntryPoint argument is the name of the binary, which is the name declared in the `gui_scripts` string spec\n- There are several optional arguments which can be found in the full library documentation.\n- The `gui_configure` function can take command line arguments as desired to provide custom functionality, such as not producing certain icons.\n- The configuration function could also be a GUI itself that allows users to select options before running.\n- Either way, the responsibility of documenting this belongs with the package manager. \n- Once instantiated and set up properly, the EntryPoint instances have a `run()` method that should be called to actually take action. \n- This new `gui_configure` function should be declared as an entry point in the package `setup()` call with a name like `{package_name}_configure`\n\nIn addition to setting up this nice launch process, there is more polishing that can be done to enhance the user experience.\nWhen these links are executed, and the Pip installed executable opens, the taskbar icon will just be the Python logo.\nThis is due to how Pip prepares these executable shims, and it is difficult to figure out how to correctly apply a taskbar icon.\nThis library provides a worker function that should address this problem.\nIn the GUI code, (Tkinter, etc.), simply import this library (`from plan_tools.runtime import fixup_taskbar_icon_on_windows`),\nand then call that function with a program name (`fixup_taskbar_icon_on_windows('This Cool GUI')`).\nThe taskbar should now show the same icon that was registered as the program icon using the GUI library. \n\n### Testing\n\nSteps to Test:\n\n- Note which Python executable is being used\n- If you are running a virtual environment, you should activate the environment or be ready to use full paths to the binaries inside the virtual environment\n- Pip install the test project `pip install plan_tools_test`\n- The folder name that Pip uses to place the executable shims is \"Scripts\" on Windows and \"bin\" on Mac/Linux, we'll say `{bin}` for now.\n- You should be able to test run the test executable if desired: \n - If your Python Scripts folder is on PATH, you can run it directly: `plan_tools_test_run`\n - If not, you may need to provide the path: `{path/to/venv}/{bin}/plan_tools_test_run` \n- Next run the configuration executable:\n - If your Python Scripts folder is on PATH, you can run it directly: `plan_tools_test_configure`\n - If not, you may need to provide the path: `{path/to/venv}/{bin}/plan_tools_test_configure`\n- The outcome depends on the operating system:\n - On Windows, by default this should add a new desktop icon for the test package and also a start menu entry for it\n - On Linux, specifically Ubuntu (Gnome Shell), you should now be able to open the applications browser and search for Plan, and find the test executable\n - On Mac, unfortunately, we don't yet support generating an .app bundle, but that should come soon, in which case the application could be found in the Spotlight\n\nThese tests have been completed:\n\n- Windows Virtual Environment:\n - OS: Windows\n - Python Install Location: C:\\Python38\n - Python Environment: venv\n - Virtual Environment Location: C:\\tmp\\venv\n - Desktop Links\n\n\n",
"bugtrack_url": null,
"license": "ModifiedBSD",
"summary": "A set of tools to help with Pip Links And Nonsense",
"version": "0.6",
"split_keywords": [
"energyplus"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "096dd175b737d8bcae34da469257aaa6b07d39d36db40fc2e9eb6218d81c2d2c",
"md5": "5cff2533ce29098d7fea0d300d7d10f7",
"sha256": "6ce812f3e55768d6b5576d6a8cc99ee50b17ae823ba5edd683a01e0d02a44ae8"
},
"downloads": -1,
"filename": "PLAN_Tools-0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5cff2533ce29098d7fea0d300d7d10f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 11264,
"upload_time": "2023-04-24T14:35:38",
"upload_time_iso_8601": "2023-04-24T14:35:38.611479Z",
"url": "https://files.pythonhosted.org/packages/09/6d/d175b737d8bcae34da469257aaa6b07d39d36db40fc2e9eb6218d81c2d2c/PLAN_Tools-0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44022afd83287e71fd5c645f4f1cfacc2cca40f485ad5898cb95e686aae839eb",
"md5": "7eb6a16c016f4b266ec76e7fe5be3f08",
"sha256": "051ff8fea5d75001480db69e9fbca18eed35d93078e6ae2063d0538c172f5274"
},
"downloads": -1,
"filename": "PLAN-Tools-0.6.tar.gz",
"has_sig": false,
"md5_digest": "7eb6a16c016f4b266ec76e7fe5be3f08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 10296,
"upload_time": "2023-04-24T14:35:40",
"upload_time_iso_8601": "2023-04-24T14:35:40.483353Z",
"url": "https://files.pythonhosted.org/packages/44/02/2afd83287e71fd5c645f4f1cfacc2cca40f485ad5898cb95e686aae839eb/PLAN-Tools-0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-24 14:35:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Myoldmopar",
"github_project": "PlanTools",
"lcname": "plan-tools"
}
JSON
