Create initial template for cmd2 plugin

Author: kotfu

.gitignore

@@ -25,17 +25,13 @@ wheels/
 .installed.cfg
 *.egg
 
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
 # Installer logs
 pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+.tox
+.pytest_cache
 htmlcov/
 .tox/
 .coverage
@@ -50,35 +46,12 @@ coverage.xml
 *.mo
 *.pot
 
-# Django stuff:
-*.log
-local_settings.py
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
 # Sphinx documentation
 docs/_build/
 
-# PyBuilder
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
 # pyenv
 .python-version
 
-# celery beat schedule file
-celerybeat-schedule
-
-# SageMath parsed files
-*.sage.py
-
 # dotenv
 .env
 
@@ -87,15 +60,8 @@ celerybeat-schedule
 venv/
 ENV/
 
-# Spyder project settings
-.spyderproject
-.spyproject
-
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
-
 # mypy
 .mypy_cache/

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+### Added
+- Created plugin template and initial documentation
+
+

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 python-cmd2
+Copyright (c) 2018 Jared Crapo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -0,0 +1,47 @@
+# Creating a plugin for cmd2
+
+## Using this template
+
+This template assumes you are creating a new cmd2 plugin called `myplugin`. I expect you will want
+to give your plugin a different name. You will need to rename some of the files and directories
+in this template to your own package name. Don't forget to modify the imports and `setup.py`.
+
+You'll probably also want to rewrite the README :)
+
+## Naming
+You should prefix the name of your project with `cmd2-`. Within that project, you should have a package with a prefix of `cmd2_`.
+
+## License
+
+Cmd2 uses the very liberal MIT license. We invite plugin authors to
+consider doing the same.
+
+## Tests
+
+Make sure you test on all versions of python supported by `cmd2`, and on
+all supported platforms. `cmd2` uses a three tiered testing strategy to
+accomplish this objective.
+
+- [pytest](https://pytest.org) runs the unit tests
+- [tox](https://tox.readthedocs.io/) runs the unit tests on multiple versions
+  of python
+- [AppVeyor](https://www.appveyor.com/) and [TravisCI](https://travis-ci.com)
+  run the tests on the various supported platforms
+
+AppVeyor and TravisCI offer free plans for open source projects.
+
+
+## Examples
+
+Include an example or two in the `examples` directory that shows a developer how your plugin
+works, and how to utilize it from within their application.
+
+
+## Distribution and Packaging
+
+When creating your `setup.py` file, keep the following in mind:
+
+- use the keywords `cmd2 plugin` to make it easier for people to find your plugin
+- since `cmd2` uses semantic versioning, you should use something like `install_requires=['cmd2 >= 0.9.0, <=2']` to make sure that your plugin doesn't try and run with a future version of `cmd2` with which it may not be compatible
+
+

cmd2_myplugin/__init__.py

@@ -0,0 +1,8 @@
+#
+# -*- coding: utf-8 -*-
+"""Description of myplugin
+
+An overview of what myplugin does.
+"""
+
+from .myplugin import myplugin_decorator, MypluginMixin

cmd2_myplugin/myplugin.py

@@ -0,0 +1,20 @@
+#
+# -*- coding: utf-8 -*-
+
+import functools
+from typing import Callable
+
+def myplugin_decorator(func: Callable) -> Callable:
+    """An empty decorator for myplugin"""
+    #@functools.wraps(func)
+    def _myplugin_decorator(self, *args, **kwargs):
+        self.poutput("in the myplugin decorator")
+        func(self, *args, **kwargs)
+    _myplugin_decorator.__doc__ = func.__doc__
+    return _myplugin_decorator
+
+class MypluginMixin:
+    """A mixin class which adds methods to a cmd2 subclass"""
+    def do_myplugin(self, arg):
+        """Add a myplugin command to cmd2"""
+        self.poutput("just ran my plugin command")

examples/example.py

@@ -0,0 +1,18 @@
+#
+# -*- coding: utf-8 -*-
+
+import cmd2
+import cmd2_myplugin
+
+class PluginExample(cmd2.cmd2.Cmd, cmd2_myplugin.MypluginMixin):
+    """An class to show how to use a plugin"""
+    def __init__(self):
+        super().__init__()
+
+    @cmd2_myplugin.myplugin_decorator
+    def do_something(self, arg):
+        self.poutput(arg)
+
+if __name__ == '__main__':
+    app = PluginExample()
+    app.cmdloop()

setup.py

@@ -0,0 +1,49 @@
+#
+# -*- coding: utf-8 -*-
+
+import os
+import setuptools
+
+#
+# get the long description from the README file
+here = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(here, 'README.md'), encoding='utf-8') as f:
+    long_description = f.read()
+
+VERSION='0.1.0'
+
+setuptools.setup(
+    name='cmd2-myplugin',
+    version=VERSION,
+    description='A template used to build plugins for cmd2',
+    long_description=long_description,
+    keywords='cmd2 plugin',
+
+    author='Kotfu',
+    author_email='[email protected]',
+    url='https://github.com/python-cmd2/cmd2-plugin-template',
+    license='MIT',
+
+    packages=['cmd2_myplugin'],
+
+    python_requires='>=3.4',
+    install_requires=['cmd2 >= 0.9.0, <=2'],
+
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Environment :: Console',
+        'Operating System :: OS Independent',
+        'Topic :: Software Development :: Libraries :: Python Modules',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+    ],
+
+    # dependencies for development and testing
+    # $ pip install -e .[dev]
+    extras_require={
+        'dev': ['pytest']
+    },
+)