{ "info": { "author": "Vincent Barth", "author_email": "vdbarth@posteo.at", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3 :: Only" ], "description": "===========\nupersetter\n===========\nupersetter helps with automating basic setup tasks for any kind of project in a general way.\nIt provides the ability to describe a project in yaml format and create files and folders based on that.\n\nupersetter uses a full-featured templating engine (jinja2) in order to allow custom variables to be used when creating a new project.\nIt also features an interactive mode to allow guided project creation for end-users.\n\nLearn more about why this project exists and how it is different to e.g. cookiecutter in the section `Why another bootstrapping tool`_.\nIf you are interested in learning more there are `examples `_. which illustrate some usecases.\n\n\n- `Installation`_\n\n - `Dependencies`_\n\n- `Basic Usage`_\n- `Advanced usage`_\n\n - `Structure syntax`_\n\n - `File creation - The files directive`_\n - `Fetching remote resources - The remote directive`_\n - `Executing external scripts - The scripts directive`_\n\n - `Templates within structure files`_\n\n - `The options file - using templates`_\n - `Interactive usage`_\n\n- `Why another bootstrapping tool`_\n- `Contributing`_\n- `License`_\n\n\nInstallation\n============\nupersetter is available on pypi::\n\n pip install upersetter\n\n\nDependencies\n------------\nupersetter has the ability to fetch content from remote sources. This is done via `AnyPath `_\nAnypath and has the same dependencies as Anypath does for the different protocols.\n\n(upersetter depends on AnyPath but AnyPath does not install any dependencies for the different protocols by default)\n\n\nBasic Usage\n===========\nDescribing your project can be done either in the form of yaml files or in code as dictionaries.\n\nIn the most basic case you describe the structure of your project in a file called *structure.yaml*::\n\n topfolder:\n :files:\n - afile:\n content: somecontent\n subfolder:\n subsubfolder:\n :files:\n - anotherfile:\n content: {{anotherfile.content}}\n\n`{{anotherfile.content}}` is a template expression which can be resolved by specifying the variable antotherfile.content in a *options.yaml* file::\n\n anotherfile:\n content: Some content for the file\n\nThe template expression can also be resolved by interactive usage of upersetter where you can specify the variable on the commandline (see `Interactive Usage`_)\n\nGiven you the files :code:`structure.yaml` and :code:`options.yaml` are in a folder called /user/example you can execute the following::\n\n python -m upersetter setup folder /user/example\n\nThe project will then be created in your current working directory.\n\nIn the above example upersetter will create a folder with the name *topfolder*.\nUnderneath that a file with the name *afile* and the content *somecontent*, as well as a folder with the name *subfolder* will be created.\n*subfolder* again has a subfolder *subsubfolder* which contains the file *anotherfile* with the content *Some content for the file* which is specified in the options.yaml file.\n\nHowever upersetter provides much more dynamic ways to create a project from templates, the commandline or even remote resources.\n\nAdvanced usage\n==============\nFull featured examples can be found in the examples_ folder which shows usages of all features available.\n\nStructure syntax\n----------------\nA structure file primarily contains two kinds of elements: folders and files\n\nIn general the structure file resembles a directory tree, however there is some special syntax to denote how files and folders should be created or filled with content.\n\nIn general a structure file looks like this::\n\n :\n :\n :files:\n - :\n \n :files:\n - :\n \n :\n ::\n ...\n\nFolders are a dictionary keys in the yaml file. Folders can have files and other folders as sub-entries::\n\n topfolder:\n subfolder:\n ...\n another topfolder:\n ...\n\n\nFiles and folders can be created in three different ways - called directives. The following directives are available:\n\n- :code:`:files:`\n- :code:`:remote:`\n- :code:`:script:`\n\nFile creation - The files directive\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThe files directive creates files either from a template or directly from given content strings.\nIt is indicated with :code:`:files:`\n\nAfter that a list of key value pairs representing the filename as the key and the way how to create the file as the value describes the files::\n\n\n :files:\n - somefile.txt:\n \n\nFiles can be created in the following ways:\n\n**content**\n:code:`content` is the simplest way to create a file. The content of the file is directly specified in the structure file::\n\n\n :files:\n - somefile.txt:\n content: This is the content of the file.\n\n**template**\n:code:`template` takes the content to be used in a file from a template which is interpreted with the options from the options file::\n\n\n :files:\n - somefile.txt:\n template: /path/to/the/template.txt\n\nThe template name doesn't need to match the name of the file to be created. The template gets rendered with the options as variables and then written to the specified filepath.\nA full explanation of template-rendering and the options file is given below: `Options and templates`_\n\n\nFetching remote resources - The remote directive\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThe remote directive takes a file or folders from a remote location and copies it in the specified directory.\nIt is indicated with :code:`:remote:`\n\n:code:`remote` is always placed directly underneath a folder::\n\n topfolder:\n subfolder:\n :remote: 'ssh://user@host:/home/user'\n\nIn this example the folder *subfolder* will have the contents of the remote folder after upersetter is executed. If the remote is only a file, only that will be copied to the local directory, else the whole directory tree will be copied.\nThe remote handling is done by `AnyPath `_ - see there to check out supported protocols from where to fetch remote resources.\n\n\nExecuting external scripts - The scripts directive\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThe script directive executes a given script in the given directory.\nIt is indicated with :code:`:script:`\n\nThe script itself follows the file directive and can either be created via a template or directly from a string::\n\n topfolder:\n :script:\n from:\n - file_info.py:\n template: file_info.py\n run:\n - python\n - file_info.py\n\n*run* specifies the actual call of the script, it is a list which will be passed to subprocess and follows the same rules, examples::\n\n ['interpreter', 'script', 'arg', 'arg2']\n ['script', '-arg', 'foo']\n\n\nTemplates within structure files\n--------------------------------\nIt is possible to use the full range of template syntax and interpolation within structure files.\nThis allows for example to dynamically specify names of files and folders, to use loops to create files and folders and much more::\n\n {{dynamic_name_of_topfolder}}:\n :files:\n {{dynamic_name_of_file}}\n\nBy default a template gets the root scope of the options to evaluate. This means that it has access to everything even if the template evaluation was called from within a template loop.\nSometimes it is desirable to pass the current block scope instead of the root - especially if the template is called from within a loop and should access exactly whatever is in the current iteration.\n\nThis can be achieved by passing a context::\n\n {% for item in items %} {{item.name}}:\n :files:\n - some_file:\n template: {file: some_template, context: {{item}} }\n {% endfor %}\n\n\nThe options file - using templates\n----------------------------------\ntbd\n\nInteractive usage\n-----------------\ntbd\n\nWhy another bootstrapping tool\n==============================\nupersetter aims to be simple and flexible. Some of the design goals do not align with other projects that solve the same need for setting up folders and files in a reproducible and easy way.\nThis section should explain why another approach was taken and why upersetter exists.\n\nIn the python world `cookiecutter `_ is a popular project that achieves the same goal as upersetter.\nIt differs in a variety of ways, which makes it suitable for different kind of projects and styles of approaching the problem.\nIf you are not familiar with cookiecutter, check it out and give it a try, it is an amazing project which is very mature (which cannot be said for upersetter as this point)\n\nOne of the main differences is that upersetter describes the directory structure in a file. cookiecutter for example uses the filesystem itself and puts placeholders in e.g. folder names.\nOn one hand this makes it easier to see how the result will look like, on the other hand describing the whole structure in a file makes it easier to do things like creating multiple subfolders based on user input.\n\nuppersetter also works with nested input parameters whereas cookiecutter uses flat descriptions.\n\nContributing\n============\nYou can contribute in any of the following areas, no matter if it is your first OSS contribution or your thousandths.\nContributions are welcome for example:\n- If you find any issue or bug when using upersetter\n- If you want to add to the documentation or fix incorrect or missing documentation.\n- If you want to add features or work on the codebase in general\n\nJust file an issue in the tracker first describing what you would like to do and then create a pull-request.\n\nLicense\n=======\nupersetter is licensed under \"Mozilla Public License Version 2.0\". See LICENSE.txt for the full license.\n\n", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/vaubarth/upersetter", "keywords": "", "license": "Mozilla Public License 2.0 (MPL 2.0)", "maintainer": "", "maintainer_email": "", "name": "upersetter", "package_url": "https://pypi.org/project/upersetter/", "platform": "", "project_url": "https://pypi.org/project/upersetter/", "project_urls": { "Homepage": "https://github.com/vaubarth/upersetter" }, "release_url": "https://pypi.org/project/upersetter/0.8.6/", "requires_dist": [ "jinja2", "pyyaml", "dpath", "click", "anypath" ], "requires_python": "", "summary": "upersetter helps with automating basic setup tasks for any kind of project in a general way.", "version": "0.8.6" }, "last_serial": 4053133, "releases": { "0.8.6": [ { "comment_text": "", "digests": { "md5": "32b665dd0429c81f90e197241fb42cf4", "sha256": "6921e406b40cf38518f6bf7d4474e6ed8350460ef402851d0760a8dbe4c37958" }, "downloads": -1, "filename": "upersetter-0.8.6-py3-none-any.whl", "has_sig": false, "md5_digest": "32b665dd0429c81f90e197241fb42cf4", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 14796, "upload_time": "2018-07-12T05:44:28", "url": "https://files.pythonhosted.org/packages/de/1c/743ddfd7c4e6354ab99e63fca65e21c67fd6880d7d75e3f7757ffd91e1c5/upersetter-0.8.6-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "63a0d5ab264782cad1dceece811bb251", "sha256": "1811d41981eecb3a57851a011eddd5503d56e8d851406a14d627445ae671c595" }, "downloads": -1, "filename": "upersetter-0.8.6.tar.gz", "has_sig": false, "md5_digest": "63a0d5ab264782cad1dceece811bb251", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12754, "upload_time": "2018-07-12T05:44:30", "url": "https://files.pythonhosted.org/packages/5a/a8/3faeca0fadbb6ea30050c4de2289bb31b61d7105a8bd500c682ec91c15f6/upersetter-0.8.6.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "32b665dd0429c81f90e197241fb42cf4", "sha256": "6921e406b40cf38518f6bf7d4474e6ed8350460ef402851d0760a8dbe4c37958" }, "downloads": -1, "filename": "upersetter-0.8.6-py3-none-any.whl", "has_sig": false, "md5_digest": "32b665dd0429c81f90e197241fb42cf4", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 14796, "upload_time": "2018-07-12T05:44:28", "url": "https://files.pythonhosted.org/packages/de/1c/743ddfd7c4e6354ab99e63fca65e21c67fd6880d7d75e3f7757ffd91e1c5/upersetter-0.8.6-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "63a0d5ab264782cad1dceece811bb251", "sha256": "1811d41981eecb3a57851a011eddd5503d56e8d851406a14d627445ae671c595" }, "downloads": -1, "filename": "upersetter-0.8.6.tar.gz", "has_sig": false, "md5_digest": "63a0d5ab264782cad1dceece811bb251", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 12754, "upload_time": "2018-07-12T05:44:30", "url": "https://files.pythonhosted.org/packages/5a/a8/3faeca0fadbb6ea30050c4de2289bb31b61d7105a8bd500c682ec91c15f6/upersetter-0.8.6.tar.gz" } ] }