jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/738576 )

Change subject: [IMP] Make a pywikibot entry point for scripts ......................................................................

[IMP] Make a pywikibot entry point for scripts

- add pwb.py wrapper script to the site-package. This enables scripts to be invoked whose paths were added to the config.user_script_paths inside user-config.py. Further implementations can provide entry points of foreign pypi packages. The pwb.py script will be copied to the new pywikibot.scripts folder when creating a dist. - Add a new pywikibot.scripts folder to the framework - move version.py script from scripts folder to pywikibot.scripts to enable version call within site-package - add a code entry point in setup that pwb.py wrapper script can be always called with "pwb" within every folder - update documentation in several files

pwb.py - rename main() function to execute - move check_modules call to main() function - add run() function as entry point for site-package and don't check package dependencies for a site-package because it is already done during installation - use base_dir instead of _pwb_dir for testpath path - add _pwb_dir to script_paths if pywikibot is a site-package, otherwise add pywikibot.scripts

Bug: T270480 Bug: T139143 Change-Id: I51160dc4df95b59bac98acf9f4e170232c4923a2 --- M README.rst M docs/api_ref/pywikibot.config.rst M docs/scripts/scripts.rst M docs/utilities/index.rst M pwb.py M pywikibot/CONTENT.rst M pywikibot/DIRECTORIES.rst M pywikibot/config.py A pywikibot/scripts/__init__.py R pywikibot/scripts/version.py M scripts/README.rst M setup.py 12 files changed, 107 insertions(+), 26 deletions(-)

Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified

diff --git a/README.rst b/README.rst index 4a02555..eebbf97 100644 --- a/README.rst +++ b/README.rst @@ -50,6 +50,7 @@

pip install -U setuptools pip install pywikibot + pwb <scriptname>

In addition a MediaWiki markup parser is required. Please install one of them:

diff --git a/docs/api_ref/pywikibot.config.rst b/docs/api_ref/pywikibot.config.rst index 290636c..c31852a 100644 --- a/docs/api_ref/pywikibot.config.rst +++ b/docs/api_ref/pywikibot.config.rst @@ -39,6 +39,8 @@ :start-at: # ############# LOGFILE SETTINGS :end-before: # #############

+.. _external-script-path-settings: + External Script Path Settings +++++++++++++++++++++++++++++

diff --git a/docs/scripts/scripts.rst b/docs/scripts/scripts.rst index 6a9371a..86ec7d3 100644 --- a/docs/scripts/scripts.rst +++ b/docs/scripts/scripts.rst @@ -252,11 +252,6 @@

.. automodule:: scripts.upload

-version script --------------- - -.. automodule:: scripts.version - watchlist script ----------------

diff --git a/docs/utilities/index.rst b/docs/utilities/index.rst index 96131fa..9965397 100644 --- a/docs/utilities/index.rst +++ b/docs/utilities/index.rst @@ -6,6 +6,11 @@

.. automodule:: pwb

+version script +-------------- + +.. automodule:: pywikibot.scripts.version + generate_family_file script -----------------------------

diff --git a/pwb.py b/pwb.py index b8ddd82..3f23bc3 100755 --- a/pwb.py +++ b/pwb.py @@ -2,10 +2,27 @@ # -*- coding: utf-8 -*- """Wrapper script to invoke pywikibot-based scripts.

+This wrapper script invokes script by its name in this search order: + +1. Scripts listed in `user_script_paths` list inside your `user-config.py` + settings file in the given order. Refer + :ref:`External Script Path Settings<external-script-path-settings>`. +2. User scripts residing in `scripts/userscripts` (directory mode only). +3. Scripts residing in `scripts` folder (directory mode only). +4. Maintenance scripts residing in `scripts/maintenance` (directory mode only). +5. Framework scripts residing in `pywikibot/scripts`. + +This wrapper script is able to invoke scripts even the script name is +missspelled. In directory mode it also checks package dependencies. + Run scripts with pywikibot in directory mode using::

python pwb.py <pwb options> <name_of_script> <options>

+or run scripts with pywikibot installed as a site package using:: + + pwb <pwb options> <name_of_script> <options> + This wrapper script uses the package directory to store all user files, will fix up search paths so the package does not need to be installed, etc.

@@ -13,6 +30,9 @@ for tests to set the default site (see T216825)::

python pwb.py -lang:de bot_tests -v + +.. versionchanged:: 7.0 + pwb wrapper was added to the Python site package lib """ # (C) Pywikibot team, 2012-2021 # @@ -32,6 +52,7 @@

pwb = None +site_package = False

def check_pwb_versions(package): @@ -235,12 +256,6 @@ return not missing_requirements

-try: - if not check_modules(): - raise RuntimeError('') # no further output needed -except RuntimeError as e: # setup.py may also raise RuntimeError - sys.exit(e) - from pathlib import Path # noqa: E402

@@ -333,9 +348,15 @@ """Search for the filename in the given script paths.""" from pywikibot import config

- script_paths = ['scripts.userscripts', - 'scripts', - 'scripts.maintenance'] + if site_package: + script_paths = [_pwb_dir] + else: + script_paths = [ + 'scripts.userscripts', + 'scripts', + 'scripts.maintenance', + 'pywikibot.scripts', + ]

if config.user_script_paths: if isinstance(config.user_script_paths, list): @@ -349,7 +370,7 @@ for file_package in script_paths: package = file_package.split('.') paths = package + [filename] - testpath = os.path.join(_pwb_dir, *paths) + testpath = os.path.join(config.base_dir, *paths) if os.path.exists(testpath): filename = testpath break @@ -359,8 +380,12 @@ return filename

-def main(): - """Command line entry point.""" +def execute(): + """Parse arguments, extract filename and run the script. + + .. versionadded:: 7.0 + renamed from :func:`main` + """ global filename

if global_args: # don't use sys.argv @@ -419,6 +444,32 @@ return True

-if __name__ == '__main__': - if not main(): +def main(): + """Script entry point. Print doc if necessary. + + .. versionchanged:: 7.0 + previous implementation was renamed to :func:`execute` + """ + try: + if not check_modules(): + raise RuntimeError('') # no further output needed + except RuntimeError as e: # setup.py may also raise RuntimeError + sys.exit(e) + + if not execute(): print(__doc__) + + +def run(): + """Site package entry point. Print doc if necessary. + + .. versionadded:: 7.0 + """ + global site_package + site_package = True + if not execute(): + print(__doc__) + + +if __name__ == '__main__': + main() diff --git a/pywikibot/CONTENT.rst b/pywikibot/CONTENT.rst index e4398a8..deb5c3e 100644 --- a/pywikibot/CONTENT.rst +++ b/pywikibot/CONTENT.rst @@ -113,6 +113,16 @@

+----------------------------+------------------------------------------------------+ + | scripts | Framework helper scripts and entry points | + +============================+======================================================+ + | pwb.py | code entry wrapper script (site-package only) | + +----------------------------+------------------------------------------------------+ + | version.py | Outputs Pywikibot's revision number, Python's | + | | version and OS used. | + +----------------------------+------------------------------------------------------+ + + + +----------------------------+------------------------------------------------------+ | site | Module with classes for MediaWiki sites | +============================+======================================================+ | __init__.py | Objects representing MediaWiki sites (wikis) | diff --git a/pywikibot/DIRECTORIES.rst b/pywikibot/DIRECTORIES.rst index d2b3c1b..0e930a6 100644 --- a/pywikibot/DIRECTORIES.rst +++ b/pywikibot/DIRECTORIES.rst @@ -14,6 +14,8 @@ +---------------------------+------------------------------------------------------+ | pywikibot/page | Module with classes for MediaWiki page content | +---------------------------+------------------------------------------------------+ + | pywikibot/scripts | Framework helper scripts | + +---------------------------+------------------------------------------------------+ | pywikibot/site | Module with classes for MediaWiki sites | +---------------------------+------------------------------------------------------+ | pywikibot/specialbots | Module containing special bots reusable by scripts | diff --git a/pywikibot/config.py b/pywikibot/config.py index d573ada..beff1fa 100644 --- a/pywikibot/config.py +++ b/pywikibot/config.py @@ -572,15 +572,18 @@ # ############# EXTERNAL SCRIPT PATH SETTINGS ############## # Set your own script path to lookup for your script files. # -# Your private script path must be located inside the -# framework folder, subfolders must be delimited by '.'. -# every folder must contain an (empty) __init__.py file. +# Your private script path is relative to your base directory. +# Subfolders must be delimited by '.'. every folder must contain +# an (empty) __init__.py file. # # The search order is # 1. user_script_paths in the given order # 2. scripts/userscripts # 3. scripts # 4. scripts/maintenance +# 5. pywikibot/scripts +# +# 2. - 4. are available in directory mode only # # sample: # user_script_paths = ['scripts.myscripts'] diff --git a/pywikibot/scripts/__init__.py b/pywikibot/scripts/__init__.py new file mode 100644 index 0000000..5a69b88 --- /dev/null +++ b/pywikibot/scripts/__init__.py @@ -0,0 +1,6 @@ +"""Folder which holds framework scripts. + +When uploading pywikibot to pypi the pwb.py (wrapper script) is copied here. + +.. versionadded:: 7.0 +""" diff --git a/scripts/version.py b/pywikibot/scripts/version.py similarity index 96% rename from scripts/version.py rename to pywikibot/scripts/version.py index 9a2cf3d..77faad0 100755 --- a/scripts/version.py +++ b/pywikibot/scripts/version.py @@ -1,5 +1,9 @@ #!/usr/bin/python -"""Script to determine the Pywikibot version (tag, revision and date).""" +"""Script to determine the Pywikibot version (tag, revision and date). + +.. versionchanged:: 7.0 + version script was moved to the framework scripts folder +""" # # (C) Pywikibot team, 2007-2021 # diff --git a/scripts/README.rst b/scripts/README.rst index c61f5d9..c4bf53f 100644 --- a/scripts/README.rst +++ b/scripts/README.rst @@ -145,9 +145,6 @@ +------------------------+---------------------------------------------------------+ | upload.py | Upload an image to a wiki. | +------------------------+---------------------------------------------------------+ - | version.py | Outputs Pywikibot's revision number, Python's version | - | | and OS used. | - +------------------------+---------------------------------------------------------+ | watchlists.py | Allows access to the account's watchlist. | +------------------------+---------------------------------------------------------+ | weblinkchecker.py | Check if external links are still working. | diff --git a/setup.py b/setup.py index c11224f..9615a85 100644 --- a/setup.py +++ b/setup.py @@ -256,6 +256,11 @@ download_url=metadata.__download_url__, test_suite='tests.collector', tests_require=test_deps, + entry_points={ + 'console_scripts': [ + 'pwb = pywikibot.scripts.pwb:run', + ], + }, classifiers=[ 'Development Status :: 5 - Production/Stable', 'Environment :: Console',