Skip to content

Latest commit

 

History

History
116 lines (85 loc) · 5.74 KB

README.md

File metadata and controls

116 lines (85 loc) · 5.74 KB
Raw

mkproj

Overview

This is a family of simple shell commands for setting up a Python project folder.

The family consists of three callable functions:

$ mkproj <-- the parent
$ mkvenv <-- child #1
$ mkrepo <-- child #2


The parent function, $ mkproj, relies on its two child functions to operate. The child functions are set up to work independently.

Let's look at what this trio of functions can do together.


Goal: Make a Python project folder.

What would we like to give this folder?

  • A Python virtual environment
  • A Git repository
  • A remote repository connected with the local repository

Fine.

We can call $ mkproj my-new-python-project to

  • create a new directory named my-new-python-project
  • install a Python virtual environment inside the directory
  • initialize the directory as the root of a Git repository
  • connect the local repository to a remote repository on GitHub

This is a good start. But we can do more.


Real Goal: Make a Python project folder that we can use right away.

With $ mkproj my-new-python-project we can also

  • set my-new-python-project as the active Python virtual environment for that shell session

  • use a GitHub Template Repository to automatically populate the remote my-new-python-project repo with any number of useful items:

    • .gitignore
    • README.md
    • LICENSE
    • INSTALL.md
    • whatever else!

  • sync the local my-new-python-project repo with its remote counterpart on GitHub, thus making these useful items automatically appear in our local project folder


Result: a Python project folder ready for use.

When $ mkproj my-new-python-project finishes, we will have a local folder with

  • an activated Python virtual environment (if we so choose)
  • an initalized local Git repository ""
  • a remote repository on GitHub ""
  • a set of starter items for our project ""



$ mkproj Operation

$ mkproj <directory>

  • Calling $ mkproj <directory> passes <directory> to the $ mkvenv and $ mkrepo functions, which then handle setting up <directory> as a Python project folder.

  • When $ mkproj <directory> is called, the command presents three Yes/No prompts:

    1. Activate <directory> as a Python virtual environment? y/n
    2. Initialize <directory> as the root of a local Git repository? y/n
    3. Connect <directory> with a remote repository on GitHub? y/n

Directory Behavior

  • $ mkproj <directory> -- makes <directory> (new or existing) a Python project folder inside the current working directory.
  • $ mkproj <path>/<directory> -- makes <directory> (new or existing) a Python project folder inside the <path> destination directory.
  • $ mkproj -- makes the current working directory into a Python project folder.


$ mkvenv Operation

$ mkvenv -a <directory>

  • Calling $ mkvenv -a <directory> installs a .venv folder inside <directory>. The .venv folder contains the Python resources needed to support <directory> as a Python virtual environment. The call then taps $ source to run a script named activate located in the recently-installed .venv folder. Running the activate script sets <directory> as the active Python virtual environment for that shell session. The activate script also places (<directory>) $ to the left of the command line prompt (as shown), signaling that all Python calls made within that shell environment will be routed to the Python interpreter in /<path>/<directory>/.venv. To return the Python environment to the system-wide Python install, type in $ deactivate at the command line or close the shell session and reopen.

$ mkvenv <directory>

  • Calling $ mkvenv <directory> simply installs a .venv folder inside <directory> (new or existing) without activating <directory> as the Python virtual environment.

Directory Behavior

  • $ mkvenv [-a] <directory> -- makes <directory> (new or existing) a Python project folder inside the current working directory.
  • $ mkvenv [-a] <path>/<directory> -- makes <directory> (new or existing) a Python project folder inside the <path> destination directory.
  • $ mkvenv [-a] -- makes the current working directory into a Python project folder.


$ mkrepo Operation

$ mkrepo -r <directory>

  • Calling $ mkrepo -r <directory> sends a call to the GitHub API to create a new remote repository (called <directory>) from a pre-defined template. The script then Git-initializes a new or existing local <directory> and links it with the newly-created remote repository.

$ mkrepo <directory>

  • Calling $ mkrepo <directory> simply initializes <directory> (new or existing) as the root of a local Git repository without connecting to the GitHub API.

Directory Behavior

  • $ mkrepo [-r] <directory> -- makes <directory> (new or existing) the root of a Git repository inside the current working directory.
  • $ mkrepo [-r] <path>/<directory> -- makes <directory> (new or existing) the root of a Git repository inside the <path> destination directory.
  • $ mkrepo [-r] -- makes the current working directory the root of a Git repository.


For more information:

Please see INSTALL.md for how to install $ mkproj, $ mkvenv, and $ mkrepo.
Also, for anyone interested, please view CONTRIBUTING.md for some ideas on the future direction of this project.