From 4aaeb97312dda40041beeb7a89fd067fd2d058cf Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Thu, 21 Sep 2023 12:17:47 +0200 Subject: [PATCH 1/7] added some documentation on how to use entry points --- docs/tutorials/entrypoints.rst | 94 ++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst index 71abcdd3b..d403e202c 100644 --- a/docs/tutorials/entrypoints.rst +++ b/docs/tutorials/entrypoints.rst @@ -8,10 +8,98 @@ Entry points ************ - .. todo:: - - Mention what is the purpose of entry points - - Give an example of a console entry point - Give an example of a custom entry point - Mention pluggy maybe for an example use-case? + +Introduction +============ + +Entry points provide a mechanism to advertise components of an installed +distribution to other code or users. Most notably, the ``console_scripts`` +entry points will create a command line wrapper. + +See the `PyPA documentation on entry points `_. + +Using entry points with meson-python +==================================== + +Entry points are defined in the ``pyproject.toml`` `metadata specification +`_. +No further configuration is required when using ``meson-python``. + +Console entry point +------------------- + +To show the usage of console entry points we build a simple +python script: + +.. code-block:: python + :caption: src/simpleapp/console.py + + """ + Simple test application. + + Usage: + simpleapp --help + simpleapp doc + simpleapp run [] [options] + + Options: + -h --help display this help message + --workdir-path= directory in which to run [default: none] + + """ + import docopt + + + + def main(): + args = docopt.docopt(__doc__) + # Just print the arguments for now. + print(args) + + if __name__ == "__main__": + main() + +This script will be part of a larger python package (called ``simpleapp``). +The meson build file is very simple and only installs the python sources. + +.. code-block:: meson + :caption: meson.build + + project('simpleapp', version:'0.0.1') + + + pymod = import('python') + python = pymod.find_installation('python3') + pydep = python.dependency() + + python.install_sources( + 'src/simpleapp/__init__.py', 'src/simpleapp/console.py' + , pure: true + , subdir: 'simpleapp' + ) + +The entry points are then specified in the ``pyproject.toml`` metadata specification. + + +.. code-block:: toml + :caption: pyproject.toml + + [project] + name = "simpleapp" + description = "simple app" + requires-python = ">=3.6" + dependencies = ["docopt"] + version = "0.0.1" + + [project.scripts] + simpleapp = "simpleapp.console:main" + + [build-system] + requires = ["meson", "toml", "ninja", "meson-python"] + build-backend = 'mesonpy' + + From d72adf48a21963b767c7e5b5443defbf5809a878 Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Thu, 21 Sep 2023 13:30:24 +0200 Subject: [PATCH 2/7] removed to trainling whitespace lines --- docs/tutorials/entrypoints.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst index d403e202c..65545d07d 100644 --- a/docs/tutorials/entrypoints.rst +++ b/docs/tutorials/entrypoints.rst @@ -101,5 +101,3 @@ The entry points are then specified in the ``pyproject.toml`` metadata specifica [build-system] requires = ["meson", "toml", "ninja", "meson-python"] build-backend = 'mesonpy' - - From 78faab6522027b91780bcaded965eef6f81a14bc Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Thu, 21 Sep 2023 13:31:27 +0200 Subject: [PATCH 3/7] fixed trailing whitespace --- docs/tutorials/entrypoints.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst index 65545d07d..6fa761cc7 100644 --- a/docs/tutorials/entrypoints.rst +++ b/docs/tutorials/entrypoints.rst @@ -18,7 +18,7 @@ Introduction Entry points provide a mechanism to advertise components of an installed distribution to other code or users. Most notably, the ``console_scripts`` -entry points will create a command line wrapper. +entry points will create a command line wrapper. See the `PyPA documentation on entry points `_. @@ -33,7 +33,7 @@ Console entry point ------------------- To show the usage of console entry points we build a simple -python script: +python script: .. code-block:: python :caption: src/simpleapp/console.py @@ -41,8 +41,8 @@ python script: """ Simple test application. - Usage: - simpleapp --help + Usage: + simpleapp --help simpleapp doc simpleapp run [] [options] From 581094a7f3078654946991c11fdab5fb8e205a9b Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Sat, 7 Oct 2023 09:33:55 +0200 Subject: [PATCH 4/7] added link to entrypoints --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index fa562ef17..4d0278eca 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,9 +53,9 @@ free to open an issue on our bugtracker_. :hidden: tutorials/introduction + tutorials/entrypoints -.. tutorials/entrypoints - tutorials/executable +.. tutorials/executable .. toctree:: From 809e5cb8fcf8805be342f93beb008fc1612d4c7d Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Sat, 7 Oct 2023 09:57:10 +0200 Subject: [PATCH 5/7] adapted some requested changes --- docs/tutorials/entrypoints.rst | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst index 6fa761cc7..db09f0b90 100644 --- a/docs/tutorials/entrypoints.rst +++ b/docs/tutorials/entrypoints.rst @@ -17,10 +17,12 @@ Introduction ============ Entry points provide a mechanism to advertise components of an installed -distribution to other code or users. Most notably, the ``console_scripts`` -entry points will create a command line wrapper. +distribution to other code or users. There are three type of entry-points: +those that provide commands to execute in a shell (``project.scripts``), +commands to launch a GUI (``project.gui-scripts``), and discoverable (plugin +style) entry-points (``project.entry-points.``). -See the `PyPA documentation on entry points `_. +See the `PyPA documentation on entry points `_. Using entry points with meson-python ==================================== @@ -32,8 +34,8 @@ No further configuration is required when using ``meson-python``. Console entry point ------------------- -To show the usage of console entry points we build a simple -python script: +To show the usage of console entry points we build a simple python script that +simply prints the arguments it was called with: .. code-block:: python :caption: src/simpleapp/console.py @@ -44,22 +46,27 @@ python script: Usage: simpleapp --help simpleapp doc - simpleapp run [] [options] Options: - -h --help display this help message - --workdir-path= directory in which to run [default: none] + -h --help display this help message """ - import docopt + + import argparse def main(): - args = docopt.docopt(__doc__) + parser = argparse.ArgumentParser(prog='simpleapp', description=__doc__) + parser.add_argument('-h', '--help', action='store_true') + parser.add_argument('doc', action='store_true') + + args = parser.parse_args() + # Just print the arguments for now. print(args) + if __name__ == "__main__": main() @@ -92,12 +99,11 @@ The entry points are then specified in the ``pyproject.toml`` metadata specifica name = "simpleapp" description = "simple app" requires-python = ">=3.6" - dependencies = ["docopt"] version = "0.0.1" - [project.scripts] - simpleapp = "simpleapp.console:main" - [build-system] requires = ["meson", "toml", "ninja", "meson-python"] build-backend = 'mesonpy' + + [project.scripts] + simpleapp = "simpleapp.console:main" From 667a5fc57b867c0ec6e83ba71b624a6f3fe429e3 Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Sat, 7 Oct 2023 10:07:37 +0200 Subject: [PATCH 6/7] adapted some more requested changes; test application working --- docs/tutorials/entrypoints.rst | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst index db09f0b90..7f9e1fd0b 100644 --- a/docs/tutorials/entrypoints.rst +++ b/docs/tutorials/entrypoints.rst @@ -41,15 +41,7 @@ simply prints the arguments it was called with: :caption: src/simpleapp/console.py """ - Simple test application. - - Usage: - simpleapp --help - simpleapp doc - - Options: - -h --help display this help message - + Simple test application. Just prints the arguments. """ @@ -58,7 +50,6 @@ simply prints the arguments it was called with: def main(): parser = argparse.ArgumentParser(prog='simpleapp', description=__doc__) - parser.add_argument('-h', '--help', action='store_true') parser.add_argument('doc', action='store_true') args = parser.parse_args() @@ -79,13 +70,11 @@ The meson build file is very simple and only installs the python sources. project('simpleapp', version:'0.0.1') - pymod = import('python') - python = pymod.find_installation('python3') - pydep = python.dependency() + py = import('python').find_installation('python3') + py_dep = py.dependency() - python.install_sources( - 'src/simpleapp/__init__.py', 'src/simpleapp/console.py' - , pure: true + py.install_sources( + ['src/simpleapp/__init__.py', 'src/simpleapp/console.py'] , subdir: 'simpleapp' ) @@ -102,8 +91,8 @@ The entry points are then specified in the ``pyproject.toml`` metadata specifica version = "0.0.1" [build-system] - requires = ["meson", "toml", "ninja", "meson-python"] build-backend = 'mesonpy' + requires = ["meson-python"] [project.scripts] simpleapp = "simpleapp.console:main" From 4efbb5a1b542ec90b644903ef5b40d6b3e4987ae Mon Sep 17 00:00:00 2001 From: Daniel Knuettel Date: Sat, 7 Oct 2023 11:51:45 +0200 Subject: [PATCH 7/7] removed one trailing whitespace --- docs/tutorials/entrypoints.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/entrypoints.rst b/docs/tutorials/entrypoints.rst index 7f9e1fd0b..2209529a7 100644 --- a/docs/tutorials/entrypoints.rst +++ b/docs/tutorials/entrypoints.rst @@ -43,7 +43,7 @@ simply prints the arguments it was called with: """ Simple test application. Just prints the arguments. """ - + import argparse