{"id":13501913,"url":"https://github.com/python-manage/manage","last_synced_at":"2025-03-29T10:32:25.629Z","repository":{"id":54655039,"uuid":"60796254","full_name":"python-manage/manage","owner":"python-manage","description":"Command Line Manager + Interactive Shell for Python Projects","archived":false,"fork":false,"pushed_at":"2021-02-07T12:55:59.000Z","size":106,"stargazers_count":126,"open_issues_count":11,"forks_count":15,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-24T20:42:38.766Z","etag":null,"topics":["click","commandline","commandline-interface","hacktoberfest","hacktoberfest-accepted","management","shell"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/python-manage.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-09T18:09:00.000Z","updated_at":"2025-02-24T20:28:02.000Z","dependencies_parsed_at":"2022-08-13T23:00:42.873Z","dependency_job_id":null,"html_url":"https://github.com/python-manage/manage","commit_stats":null,"previous_names":["rochacbruno/manage"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/python-manage%2Fmanage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/python-manage%2Fmanage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/python-manage%2Fmanage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/python-manage%2Fmanage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/python-manage","download_url":"https://codeload.github.com/python-manage/manage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246173937,"owners_count":20735405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["click","commandline","commandline-interface","hacktoberfest","hacktoberfest-accepted","management","shell"],"created_at":"2024-07-31T22:01:55.166Z","updated_at":"2025-03-29T10:32:25.300Z","avatar_url":"https://github.com/python-manage.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"======\nManage\n======\n------------------------------------------------------------\nCommand Line Manager + Interactive Shell for Python Projects\n------------------------------------------------------------\n\n.. image:: https://img.shields.io/pypi/v/manage.svg\n   :target: https://pypi.python.org/pypi/manage\n\n.. image:: https://github.com/python-manage/manage/workflows/tests/badge.svg\n   :target: https://github.com/python-manage/manage/actions?query=workflow%3Atests\n\n.. image:: https://readthedocs.org/projects/manage/badge/?version=latest\n   :target: https://manage.readthedocs.io/en/latest/?badge=latest\n   :alt: Documentation Status\n\n\n* Free software: ISC license\n* Documentation: https://manage.readthedocs.io.\n\n\nFeatures\n========\n\nWith **manage** you add a **command line manager** to your Python project and\nalso it comes with an interactive shell with iPython support.\n\nAll you have to do is **init** your project directory (creating the manage.yml file)\n\n.. code-block:: console\n\n    $ pip install manage\n    $ cd /my_project_root_folder\n    $ manage init\n    creating manage.yml....\n\nThe file **manage.yml** describes how **manage** command should discover your app modules and custom commands and also it\ndefines which objects should be loaded in to the **shell**\n\n.. note::\n\n   Windows users may need to install proper version of PyYAML depending on the version of that thing you call an operating system,\n   installable available in: https://pypi.python.org/pypi/PyYAML\n   **or consider using Linux and don't worry about this as everything works well in Linux except games, photoshop and solitary game :)**\n\nThe Shell\n=========\n\nBy default the command :code:`manage shell` is included, it is a simple Python REPL console with some\nconfigurable options.\n\nYou can change the banner message to say anything you want, **e.g: \"Welcome to my shell!\"** and you can also\nspecify some objects to be automatically imported in to the shell context so when you enter in to the shell you\nalready have your project's common objects available.\n\nAlso you can specify a custom function to run or a string based code block to run, useful to init and configure the objects.\n\nConsoles\n\n:code:`manage shell` can start different consoles by passing the options\n\n- :code:`manage shell --ipython`  - This is the default (if ipython installed)\n- :code:`manage shell --ptpython`\n- :code:`manage shell --bpython`\n- :code:`manage shell --python` - This is the **default Python console** including support for autocomplete. (will be default when no other is installed)\n\nThe first thing you can do with **manage** is customizing the objects that will be automatically loaded in to shell,\nsaving you from importing and initializing a lot of stuff every time you need to play with your app via console.\n\nEdit **manage.yml** with:\n\n.. code-block:: yaml\n\n    project_name: My Awesome Project\n    help_text: |\n      This is the {project_name} interactive shell!\n    shell:\n      console: bpython\n      readline_enabled: false  # MacOS has no readline completion support\n      banner:\n        enabled: true\n        message: 'Welcome to {project_name} shell!'\n      auto_import:\n        display: true\n        objects:\n          my_system.config.settings:\n          my_system.my_module.MyClass:\n          my_system.my_module.OtherClass:\n            as: NiceClass\n          sys.path:\n            as: sp\n            init:\n              insert:\n                args:\n                  - 0\n                  - /path/to/be/added/automatically/to/sys/path\n      init_script: |\n        from my_system.config import settings\n        print(\"Initializing settings...\")\n        settings.configure()\n\n\nThen the above **manage.yaml** will give you a shell like this:\n\n.. code-block:: console\n\n    $ manage shell\n    Initializing settings...\n    Welcome to My Awesome Project shell!\n        Auto imported: ['sp', 'settings', 'MyClass', 'NiceCLass']\n    \u003e\u003e\u003e  NiceClass. \u003ctab\u003e # autocomplete enabled\n\n\nWatch the demo:\n\n|asciicast|\n\n.. |asciicast| image:: https://asciinema.org/a/51042.png\n   :target: https://asciinema.org/a/51042\n\nCheck more examples in:\n\nhttps://github.com/rochacbruno/manage/tree/master/examples/\n\nThe famous **naval fate** example (used in docopt and click) is in:\n\nhttps://github.com/rochacbruno/manage/tree/master/examples/naval/\n\n\nProjects using manage\n=====================\n\n- Quokka CMS (A Flask based CMS) is using manage\n- Red Hat Satellite QE tesitng framework (robottelo) is using manage\n\nCustom Commands\n===============\n\nSometimes you need to add custom commands in to your project\ne.g: A command to add users to your system::\n\n  $ manage create_user --name=Bruno --passwd=1234\n  Creating the user...\n\n**manage** has some different ways for you to define custom commands,\nyou can use **click commands** defined in your project modules,\nyou can also use **function_commands** defined anywhere in your project,\nand if really needed can define **inline_commands** inside the **manage.yml** file\n\n1. Using a custom click_commands module (single file)\n-----------------------------------------------------\n\nLets say you have a commands module in your application, you write your custom command there and **manage** will load it\n\n.. code-block:: python\n\n  # myproject/commands.py\n  import click\n  @click.command()\n  @click.option('--name')\n  @click.option('--passwd')\n  def create_user(name, passwd):\n      \"\"\"Create a new user\"\"\"\n      click.echo('Creating the user...')\n      mysystem.User.create(name, password)\n\n\nNow you go to your **manage.yml** or **.manage.yml** and specify your custom command module.\n\n.. code-block:: yaml\n\n  click_commands:\n    - module: commands\n\nNow you run **manage --help**\n\n.. code-block:: console\n\n  $ manage --help\n  ...\n  Commands:\n    create_user  Create a new user\n    debug        Shows the parsed manage file\n    init         Initialize a manage shell in current...\n    shell        Runs a Python shell with context\n\n\nUsing a click_commands package (multiple files)\n-----------------------------------------------\n\nIt is common to have different files to hold your commands so you may prefer having\na **commands/** package and some **python** modules inside it to hold commands.\n\n.. code-block:: python\n\n  # myproject/commands/user.py\n  import click\n  @click.command()\n  @click.option('--name')\n  @click.option('--passwd')\n  def create_user(name, passwd):\n      \"\"\"Create a new user\"\"\"\n      click.echo('Creating the user...')\n      mysystem.User.create(name, password)\n\n.. code-block:: python\n\n  # myproject/commands/system.py\n  import click\n  @click.command()\n  def clear_cache():\n      \"\"\"Clear the system cache\"\"\"\n      click.echo('The cache will be erased...')\n      mysystem.cache.clear()\n\nSo now you want to add all those commands to your **manage** editing your manage file with.\n\n.. code-block:: yaml\n\n  click_commands:\n    - module: commands\n\nNow you run **manage --help**  and you have commands from both modules\n\n.. code-block:: console\n\n  $ manage --help\n  ...\n  Commands:\n    create_user  Create a new user\n    clear_cache  Clear the system cache\n    debug        Shows the parsed manage file\n    init         Initialize a manage shell in current...\n    shell        Runs a Python shell with context\n\nCustom click_command names\n--------------------------\n\nSometimes the name of commands differ from the name of the function so you can\ncustomize it.\n\n.. code-block:: yaml\n\n  click_commands:\n    - module: commands.system\n      config:\n        clear_cache:\n          name: reset_cache\n          help_text: This resets the cache\n    - module: commands.user\n      config:\n        create_user:\n          name: new_user\n          help_text: This creates new user\n\nHaving different namespaces\n---------------------------\n\nIf customizing the name looks too much work for you, and you are only trying to handle naming conflicts\nyou can user namespaced commands.\n\n.. code-block:: yaml\n\n  namespaced: true\n  click_commands:\n    - module: commands\n\nNow you run **manage --help** and you can see all the commands in the same module will be namespaced by **modulename_**\n\n.. code-block:: console\n\n  $ manage --help\n  ...\n  Commands:\n    user_create_user    Create a new user\n    system_clear_cache  Clear the system cache\n    debug        Shows the parsed manage file\n    init         Initialize a manage shell in current...\n    shell        Runs a Python shell with context\n\nAnd you can even customize namespace for each module separately\n---------------------------------------------------------------\n\n.. note:: If **namespaced** is true all commands will be namespaced, set it to false in order to define separately\n\n\n.. code-block:: yaml\n\n  click_commands:\n    - module: commands.system\n      namespace: sys\n    - module: commands.user\n      namespace: user\n\nNow you run **manage --help** and you can see all the commands in the same module will be namespaced.\n\n.. code-block:: console\n\n  $ manage --help\n  ...\n  Commands:\n    user_create_user  Create a new user\n    sys_clear_cache  Clear the system cache\n    debug        Shows the parsed manage file\n    init         Initialize a manage shell in current...\n    shell        Runs a Python shell with context\n\n\n2. Defining your inline commands in manage file directly\n--------------------------------------------------------\n\nSometimes your command is so simple that you do not want (or can't) have a custom module,\nso you can put all your commands in yaml file directly.\n\n.. code-block:: yaml\n\n    inline_commands:\n      - name: clear_cache\n        help_text: Executes inline code to clear the cache\n        context:\n          - sys\n          - pprint\n        options:\n          --days:\n            default: 100\n        code: |\n          pprint.pprint({'clean_days': days, 'path': sys.path})\n\n\nNow running **manage --help**\n\n.. code-block:: console\n\n  $ manage --help\n  ...\n  Commands:\n    clear_cache  Executes inline code to clear the cache\n    debug        Shows the parsed manage file\n    init         Initialize a manage shell in current...\n    shell        Runs a Python shell with context\n\n\nAnd you can run using\n\n.. code-block:: console\n\n  $ manage clear_cache --days 15\n\n3. Using general functions as commands\n--------------------------------------\nAnd if you already has some defined function (any callable works).\n\n.. code-block:: python\n\n    # my_system.functions.py\n    def create_user(name, password):\n        print(\"Creating user %s\" % name)\n\n\n\n.. code-block:: yaml\n\n    function_commands:\n      - function: my_system.functions.create_user\n        name: new_user\n        help_text: Create new user\n        options:\n          --name:\n            required: true\n          --password:\n            required: true\n\n\nNow running **manage --help**\n\n.. code-block:: console\n\n  $ manage --help\n  ...\n  Commands:\n    new_user     Create new user\n    debug        Shows the parsed manage file\n    init         Initialize a manage shell in current...\n    shell        Runs a Python shell with context\n\n  $ manage new_user --name=Bruno --password=1234\n  Creating user Bruno\n\n\nFurther Explanations\n====================\n\n- You can say, **how this is useful?**, There's no need to get a separate package and configure everything in yaml, just use iPython to do it. Besides, IPython configuration has a lot more options and capabilities.\n- So I say: Nice! **If you don't like it, dont't use it!**\n\nCredits\n=======\n\n- This is inspired by **Django's manage.py command**\n- This is based on click_\n- This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\n\n.. _click: http://click.pocoo.org\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n\nSimilar projects\n================\n\n- Cobra is a `manage` for Go language https://github.com/spf13/cobra\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpython-manage%2Fmanage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpython-manage%2Fmanage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpython-manage%2Fmanage/lists"}