Make code more cleary and readable.

Author: Igor Kalnitsky

setup.py

@@ -7,11 +7,12 @@
 setup(
     name='xsnippet-cli',
     version=version,
+    url='https://github.com/xsnippet/xsnippet-cli',
+    license='BSD License',
     author='Igor Kalnitsky',
     author_email='[email protected]',
     description='A simple command line interface for the XSnippet service.',
     long_description=open('README.rst').read(),
-    license='BSD License',
     packages=['xsnippet_cli'],
     entry_points={
         'console_scripts': ['xsnippet = xsnippet_cli.cli:main'],
@@ -29,5 +30,4 @@
         'Programming Language :: Python :: 3.2',
         'Programming Language :: Python :: 3.3',
     ],
-    url='https://github.com/xsnippet/xsnippet-cli',
 )

xsnippet_cli/__init__.py

@@ -3,25 +3,32 @@
     xsnippet_cli
     ~~~~~~~~~~~~
 
-    XSnippet CLI is a simple command line interface for interacting
-    with XSnippet service. Currently, it provides only posting and
-    receiving snippets as a Guest user.
+    **xsnippet-cli** is a simple command line interface for interacting with
+    Xsnippet_ service. By means this script, you can easily post and receive
+    Snippets directly from your terminal.
 
-    You can send a file in the following way::
+
+    Usage
+    -----
+
+    It's very easy to use. You can paste the snippet this way ::
 
         $ xsnippet /path/to/file
 
-    For sending a some command output, you can use a unix pipe system::
+    Or this way ::
+
+        $ cat /path/to/file | xsnippet
+
+    As you can see the last method posts a some command output. It's very
+    usefull To post the last few lines from logfile this way ::
 
-        $ ls -la | xsnippet
+        $ tail -n 5 nginx.log | xsnippet
 
-    If you want to retrieve a some snippet from the server, just do the
-    following command::
+    It's important to note that you can specify a snippet language or tags.
+    Thats can be done by the following command ::
 
-        $ xsnippet -r <snippet id>
+        $ cat setup.py | xsnippet -l python -t setuptools test
 
-    The script provides a some useful options such as tags or language.
-    Use ``$ xsnippet --help`` for more details.
 
     :copyright: (c) 2013 by Igor Kalnitsky.
     :license: BSD, see LICENSE for more details.

xsnippet_cli/cli.py

@@ -19,41 +19,63 @@
 from xsnippet_cli import api
 
 
-
 def main():
     """
-        An entry point of the command line interface.
+        An entry point of the command line interface. The main
+        purpose of this function is a job dispatching.
     """
     args = _parse_arguments()
 
-    if args.receive_id:
-        return receive_snippet(args.receive_id)
+    if args.receive:
+        return _receive_snippet(args.receive)
+    return _post_snippet(args.filename, args.caption, args.language, args.tags)
 
-    if args.filename:
-        return post_file(args.filename, args.language, args.tags)
-    else:
-        return post_snippet(sys.stdin.read(), None, args.language, args.tags)
 
+def _receive_snippet(snippet_id, _info=True):
+    """
+        Retrieve from the server a snippet with a given id
+        and print it to ``stdout``.
 
-def post_file(filename, language, tags):
-    title = os.path.basename(filename)
+        .. note: The function prints snippet info if the ``_info``
+                 argument is True.
+    """
+    snippet = api.get_snippet(snippet_id)
 
-    if not language:
-        language = get_lang_for_filename(filename)
+    for key, value in snippet.items():
+        if _info and value and key != 'content':
+            print(':{key}: {value}'.format(key=key, value=value))
 
-    with open(filename) as f:
-        post_snippet(f.read(), title, language, tags)
+    print(snippet['content'])
 
 
-def post_snippet(content, title, language, tags):
-    print(api.post_snippet(content, title, language, tags))
+def _post_snippet(filename=None, caption=None, language=None, tags=None):
+    """
+        Send a snippet with a given attributes to the server. If ``filename``
+        is not specify the ``stdin`` will be post.
 
+        .. note: If ``filename`` is specified the language will be defined
+                 automatically. Please note, this feature will be activated
+                 only if you not specify a language manually.
+    """
+    def get_file_info(filename, caption, language):
+        with open(filename) as f:
+            content = f.read()
+        if not caption:
+            caption = os.path.basename(filename)
+        if not language:
+            language = _get_lang_for_filename(filename)
+        return content, caption, language
+
+    if not filename:
+        content = sys.stdin.read()
+    else:
+        content, caption, language = get_file_info(filename, caption, language)
 
-def receive_snippet(id_):
-    print(api.get_snippet(id_))
+    # post snippet and print a link to the posted snippet
+    print(api.post_snippet(content, caption, language, tags))
 
 
-def get_lang_for_filename(filename):
+def _get_lang_for_filename(filename):
     try:
         aliases = get_lexer_for_filename(filename).aliases
         sname = aliases[0] if aliases else None
@@ -63,28 +85,18 @@ def get_lang_for_filename(filename):
 
 
 def _parse_arguments():
+    """
+        Parse command line arguments and returns result.
+        Execute ``$ xsnippet --help`` for more details.
+    """
     args = argparse.ArgumentParser(
         description='A simple command line interface for the XSnippet service.'
     )
 
-    args.add_argument(
-        'filename', nargs='?'
-    )
-
-    args.add_argument(
-        '-r', '--receive', dest='receive_id',
-        help='receive a snippet with a given id'
-    )
-
-    args.add_argument(
-        '-t', '--tags', dest='tags', nargs='*',
-        help='attach tags to the snippet'
-    )
-
-    args.add_argument(
-        '-l', '--language', dest='language',
-        help='attach language to the snippet'
-    )
+    args.add_argument('filename', nargs='?')
+    args.add_argument('-c', '--caption', dest='caption')
+    args.add_argument('-t', '--tags', dest='tags', nargs='*')
+    args.add_argument('-l', '--language', dest='language')
+    args.add_argument('-r', '--receive', dest='receive', metavar='ID')
 
     return args.parse_args()
-