From af9971071b328a1c942d1852e1f56d72f81f7b78 Mon Sep 17 00:00:00 2001 From: Surya Teja <94suryateja@gmail.com> Date: Sun, 16 Dec 2018 19:08:05 +0530 Subject: [PATCH 01/14] Added windows virtual environment activation command. Closes #942 --- docs/dev/virtualenvs.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 11f9248..4d629d8 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -226,23 +226,26 @@ Basic Usage .. code-block:: console $ cd my_project_folder - $ virtualenv my_project + $ virtualenv venv -``virtualenv my_project`` will create a folder in the current directory which will +``virtualenv venv`` will create a folder in the current directory which will contain the Python executable files, and a copy of the ``pip`` library which you can use to install other packages. The name of the virtual environment (in this -case, it was ``my_project``) can be anything; omitting the name will place the files +case, it was ``venv``) can be anything; omitting the name will place the files in the current directory instead. +.. note:: + 'venv' is the general convention used globally. As it is readily available in ignore files (eg: .gitignore') + This creates a copy of Python in whichever directory you ran the command in, -placing it in a folder named :file:`my_project`. +placing it in a folder named :file:`venv`. You can also use the Python interpreter of your choice (like ``python2.7``). .. code-block:: console - $ virtualenv -p /usr/bin/python2.7 my_project + $ virtualenv -p /usr/bin/python2.7 venv or change the interpreter globally with an env variable in ``~/.bashrc``: @@ -254,12 +257,20 @@ or change the interpreter globally with an env variable in ``~/.bashrc``: .. code-block:: console - $ source my_project/bin/activate + $ source venv/bin/activate The name of the current virtual environment will now appear on the left of -the prompt (e.g. ``(my_project)Your-Computer:your_project UserName$)`` to let you know +the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know that it's active. From now on, any package that you install using pip will be -placed in the ``my_project`` folder, isolated from the global Python installation. +placed in the ``venv`` folder, isolated from the global Python installation. + +For windows, same command which is mentioned in step 1 can be used for creation of virtual environment. But, to activate, we use the following command. + +Assuming that, you are in project directory: + +.. code-block:: powershell + + PS C:\Users\suryav> \venv\bin\activate Install packages as usual, for example: @@ -284,6 +295,9 @@ After a while, though, you might end up with a lot of virtual environments littered across your system, and its possible you'll forget their names or where they were placed. +.. note:: + Python has included virtual environment module from 3.3. It works in the simliar way as mentioned above. For details: `venv `_. + Other Notes ~~~~~~~~~~~ From 8a6b1c73bf685f2105682ad032c9c0d3b5f59ad6 Mon Sep 17 00:00:00 2001 From: Harish Kesava Rao Date: Sun, 16 Dec 2018 22:35:35 -0600 Subject: [PATCH 02/14] issue-938: added sections in serialization for simple file, csv, yaml, json --- docs/scenarios/serialization.rst | 142 ++++++++++++++++++++++++++++++- 1 file changed, 141 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst index 559ad36..ef4a193 100644 --- a/docs/scenarios/serialization.rst +++ b/docs/scenarios/serialization.rst @@ -12,10 +12,150 @@ What is data serialization? Data serialization is the concept of converting structured data into a format that allows it to be shared or stored in such a way that its original -structure to be recovered. In some cases, the secondary intention of data +structure can be recovered or reconstructed. In some cases, the secondary intention of data serialization is to minimize the size of the serialized data which then minimizes disk space or bandwidth requirements. +******************** +Flat vs. Nested data +******************** + +Before beginning to serialize data, it is important to identify or decide how the +data needs to be structured during data serialization - flat or nested. +The differences in the two styles are shown in the below examples. + +Flat style: + +.. code-block:: python + + { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" } + + +Nested style: + +.. code-block:: python + + {"A" + { "field1": "value1", "field2": "value2", "field3": "value3" } } + + +For more reading on the two styles, please see the discussion on +`Python mailing list `__, +`IETF mailing list `__ and +`here `__. + +**************** +Serializing Text +**************** + +======================= +Simple file (flat data) +======================= + +If the data to be serialized is located in a file and contains flat data, Python offers two methods to serialize data. + +repr +---- + +The repr method in Python takes a single object parameter and returns a printable representation of the input + +.. code-block:: python + + # input as flat text + a = { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" } + + # the same input can also be read from a file + a = + + # returns a printable representation of the input; + # the output can be written to a file as well + print(repr(a)) + + # write content to files using repr + with open('/tmp/file.py') as f:f.write(repr(a)) + +ast.literal_eval +________________ + +The literal_eval method safely parses and evaluates an expression for a Python datatype. +Supported data types are: strings, numbers, tuples, lists, dicts, booleans and None. + +.. code-block:: python + + with open('/tmp/file.py', 'r') as f: inp = ast.literal_eval(f.read()) + +==================== +CSV file (flat data) +==================== + +The CSV module in Python implements classes to read and write tabular +data in CSV format. + +Simple example for reading: + +.. code-block:: python + + import csv + with open('/tmp/file.csv', newline='') as f: + reader = csv.reader(f) + for row in reader: + print(row) + +Simple example for writing: + +.. code-block:: python + + import csv + with open('/temp/file.csv', 'w', newline='') as f: + writer = csv.writer(f) + writer.writerows(iterable) + + +The module's contents, functions and examples can be found +`here `__. + +================== +YAML (nested data) +================== + +There are many third party modules to parse and read/write YAML file +structures in Python. One such example is below. + +.. code-block:: python + + import yaml + with open('/tmp/file.yaml', 'r', newline='') as f: + try: + print(yaml.load(f)) + except yaml.YAMLError as ymlexcp: + print(ymlexcp) + +Documentation on the third party module can be found +`here `__. + +======================= +JSON file (nested data) +======================= + +Python's JSON module can be used to read and write JSON files. +Example code is below. + +Reading: + +.. code-block:: python + + import json + with open('/tmp/file.json', 'r') as f: + data = json.dump(f) + +Writing: + +.. code-block:: python + + import json + with open('/tmp/file.json', 'w') as f: + json.dump(data, f, sort_keys=True) + ****** Pickle From eb6ec707060951082c52255a658eb8e43aa173ac Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Mon, 17 Dec 2018 14:21:50 -0500 Subject: [PATCH 03/14] Typo, grammar, and style fixes --- docs/contents.rst.inc | 9 +---- docs/dev/env.rst | 70 +++++++++++++++++----------------- docs/dev/pip-virtualenv.rst | 2 +- docs/dev/virtualenvs.rst | 12 +++--- docs/scenarios/ml.rst | 2 +- docs/starting/which-python.rst | 2 +- docs/writing/documentation.rst | 10 ++--- docs/writing/gotchas.rst | 2 +- docs/writing/license.rst | 6 +-- docs/writing/logging.rst | 4 +- docs/writing/reading.rst | 6 +-- docs/writing/structure.rst | 24 ++++++------ docs/writing/style.rst | 46 +++++++++++----------- docs/writing/tests.rst | 11 +++--- 14 files changed, 100 insertions(+), 106 deletions(-) diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 76049aa..2e1e404 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -33,7 +33,7 @@ New to Python? Let's properly setup up your Python environment: Python Development Environments ------------------------------- -This part of the guide focus on the Python development environment, +This part of the guide focuses on the Python development environment, and the best-practice tools that are available for writing Python code. .. toctree:: @@ -110,7 +110,7 @@ Additional Notes ---------------- This part of the guide, which is mostly prose, begins with some -background information about Python, then focuses on next steps. +background information about Python, and then focuses on next steps. .. toctree:: :maxdepth: 2 @@ -137,8 +137,3 @@ Contribution notes and legal information (for those interested). notes/contribute notes/license notes/styleguide - - - - - diff --git a/docs/dev/env.rst b/docs/dev/env.rst index de67a9a..0862411 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -7,7 +7,7 @@ Your Development Environment Text Editors :::::::::::: -Just about anything that can edit plain text will work for writing Python code, +Just about anything that can edit plain text will work for writing Python code; however, using a more powerful editor may make your life a bit easier. @@ -97,7 +97,7 @@ using ```` key or any other customized keys. Emacs ----- -Emacs is another powerful text editor. It is fully programmable (lisp), but +Emacs is another powerful text editor. It is fully programmable (Lisp), but it can be some work to wire up correctly. A good start if you're already an Emacs user is `Python Programming in Emacs`_ at EmacsWiki. @@ -117,8 +117,8 @@ Sublime Text ------------ `Sublime Text `_ is a sophisticated text - editor for code, markup and prose. You'll love the slick user interface, - extraordinary features and amazing performance. + editor for code, markup, and prose. You'll love the slick user interface, + extraordinary features, and amazing performance. Sublime Text has excellent support for editing Python code and uses Python for its plugin API. It also has a diverse variety of plugins, @@ -133,7 +133,7 @@ Atom editors. Atom is web native (HTML, CSS, JS), focusing on modular design and easy plugin -development. It comes with native package control and plethora of packages. +development. It comes with native package control and a plethora of packages. Recommended for Python development is `Linter `_ combined with `linter-flake8 `_. @@ -156,7 +156,7 @@ Python (on Visual Studio Code) ------------------------------ `Python for Visual Studio `_ is an extension for the `Visual Studio Code IDE `_. -This is a free, light weight, open source IDE, with support for Mac, Windows, and Linux. +This is a free, lightweight, open source IDE, with support for Mac, Windows, and Linux. Built using open source technologies such as Node.js and Python, with compelling features such as Intellisense (autocompletion), local and remote debugging, linting, and the like. MIT licensed. @@ -192,7 +192,7 @@ toward working with scientific Python libraries (namely `pylint `_ and `rope `_. -Spyder is open-source (free), offers code completion, syntax highlighting, +Spyder is open source (free), offers code completion, syntax highlighting, a class and function browser, and object inspection. @@ -200,7 +200,7 @@ WingIDE ------- `WingIDE `_ is a Python specific IDE. It runs on Linux, -Windows and Mac (as an X11 application, which frustrates some Mac users). +Windows, and Mac (as an X11 application, which frustrates some Mac users). WingIDE offers code completion, syntax highlighting, source browser, graphical debugger and support for version control systems. @@ -211,11 +211,11 @@ NINJA-IDE `NINJA-IDE `_ (from the recursive acronym: "Ninja-IDE Is Not Just Another IDE") is a cross-platform IDE, specially designed to build -Python applications, and runs on Linux/X11, Mac OS X and Windows desktop +Python applications, and runs on Linux/X11, Mac OS X, and Windows desktop operating systems. Installers for these platforms can be downloaded from the website. -NINJA-IDE is open-source software (GPLv3 licence) and is developed +NINJA-IDE is open source software (GPLv3 licence) and is developed in Python and Qt. The source files can be downloaded from `GitHub `_. @@ -224,11 +224,11 @@ Eric (The Eric Python IDE) -------------------------- `Eric `_ is a full featured Python IDE -offering sourcecode autocompletion, syntax highlighting, support for version -control systems, python 3 support, integrated web browser, python shell, -integrated debugger and a flexible plug-in system. Written in python, it is -based on the Qt gui toolkit, integrating the Scintilla editor control. Eric -is an open-source software project (GPLv3 licence) with more than ten years of +offering source code autocompletion, syntax highlighting, support for version +control systems, Python 3 support, integrated web browser, python shell, +integrated debugger, and a flexible plug-in system. Written in Python, it is +based on the Qt GUI toolkit, integrating the Scintilla editor control. Eric +is an open source software project (GPLv3 licence) with more than ten years of active development. @@ -253,8 +253,8 @@ of the Python interpreter to be installed at the same time. This solves the problem of having different projects requiring different versions of Python. For example, it becomes very easy to install Python 2.7 for compatibility in one project, whilst still using Python 3.4 as the default interpreter. -pyenv isn't just limited to the CPython versions - it will also install PyPy, -anaconda, miniconda, stackless, jython, and ironpython interpreters. +pyenv isn't just limited to the CPython versions – it will also install PyPy, +Anaconda, miniconda, stackless, Jython, and IronPython interpreters. pyenv works by filling a ``shims`` directory with fake versions of the Python interpreter (plus other tools like ``pip`` and ``2to3``). When the system @@ -276,7 +276,7 @@ IDLE ---- :ref:`IDLE ` is an integrated development environment that is -part of Python standard library. It is completely written in Python and uses +part of the Python standard distribution. It is completely written in Python and uses the Tkinter GUI toolkit. Though IDLE is not suited for full-blown development using Python, it is quite helpful to try out small Python snippets and experiment with different features in Python. @@ -294,18 +294,18 @@ IPython `IPython `_ provides a rich toolkit to help you make the most out of using Python interactively. Its main components are: -* Powerful Python shells (terminal- and Qt-based). +* Powerful Python shells (terminal- and Qt-based) * A web-based notebook with the same core features but support for rich media, - text, code, mathematical expressions and inline plots. -* Support for interactive data visualization and use of GUI toolkits. -* Flexible, embeddable interpreters to load into your own projects. -* Tools for high level and interactive parallel computing. + text, code, mathematical expressions and inline plots +* Support for interactive data visualization and use of GUI toolkits +* Flexible, embeddable interpreters to load into your own projects +* Tools for high level and interactive parallel computing .. code-block:: console $ pip install ipython -To download and install IPython with all it's optional dependencies for the notebook, qtconsole, tests, and other functionalities +To download and install IPython with all its optional dependencies for the notebook, qtconsole, tests, and other functionalities: .. code-block:: console @@ -318,14 +318,14 @@ BPython Python interpreter for Unix-like operating systems. It has the following features: -* In-line syntax highlighting. -* Readline-like autocomplete with suggestions displayed as you type. -* Expected parameter list for any Python function. -* "Rewind" function to pop the last line of code from memory and re-evaluate. -* Send entered code off to a pastebin. -* Save entered code to a file. -* Auto-indentation. -* Python 3 support. +* In-line syntax highlighting +* Readline-like autocomplete with suggestions displayed as you type +* Expected parameter list for any Python function +* "Rewind" function to pop the last line of code from memory and re-evaluate +* Send entered code off to a pastebin +* Save entered code to a file +* Auto-indentation +* Python 3 support .. code-block:: console @@ -341,12 +341,12 @@ library. It is considered to be an alternative to BPython_. Features include: * Syntax highlighting * Autocompletion * Multiline editing -* Emacs and VIM Mode +* Emacs and Vim Modes * Embedding REPL inside of your code -* Syntax Validation +* Syntax validation * Tab pages * Support for integrating with IPython_'s shell, by installing IPython - ``pip install ipython`` and running ``ptipython``. + (``pip install ipython``) and running ``ptipython``. .. code-block:: console diff --git a/docs/dev/pip-virtualenv.rst b/docs/dev/pip-virtualenv.rst index 6971be8..abd80bb 100644 --- a/docs/dev/pip-virtualenv.rst +++ b/docs/dev/pip-virtualenv.rst @@ -1,6 +1,6 @@ .. _pip-virtualenv: -Further Configuration of Pip and Virtualenv +Further Configuration of pip and Virtualenv =========================================== .. image:: /_static/photos/34018732105_f0e6758859_k_d.jpg diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 11f9248..f6dff56 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -212,7 +212,7 @@ Install virtualenv via pip: $ pip install virtualenv -Test your installation +Test your installation: .. code-block:: console @@ -281,7 +281,7 @@ To delete a virtual environment, just delete its folder. (In this case, it would be ``rm -rf my_project``.) After a while, though, you might end up with a lot of virtual environments -littered across your system, and its possible you'll forget their names or +littered across your system, and it's possible you'll forget their names or where they were placed. Other Notes @@ -293,7 +293,7 @@ for keeping the package list clean in case it needs to be accessed later. [This is the default behavior for ``virtualenv`` 1.7 and later.] In order to keep your environment consistent, it's a good idea to "freeze" -the current state of the environment packages. To do this, run +the current state of the environment packages. To do this, run: .. code-block:: console @@ -302,7 +302,7 @@ the current state of the environment packages. To do this, run This will create a :file:`requirements.txt` file, which contains a simple list of all the packages in the current environment, and their respective versions. You can see the list of installed packages without the requirements -format using "pip list". Later it will be easier for a different developer +format using ``pip list``. Later it will be easier for a different developer (or you, if you need to re-create the environment) to install the same packages using the same versions: @@ -343,7 +343,7 @@ To install (make sure **virtualenv** is already installed): $ pip install virtualenvwrapper-win -In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs +In Windows, the default path for WORKON_HOME is %USERPROFILE%\\Envs Basic Usage ~~~~~~~~~~~ @@ -363,7 +363,7 @@ This creates the :file:`my_project` folder inside :file:`~/Envs`. $ workon my_project Alternatively, you can make a project, which creates the virtual environment, -and also a project directory inside ``$WORKON_HOME``, which is ``cd`` -ed into +and also a project directory inside ``$WORKON_HOME``, which is ``cd``-ed into when you ``workon myproject``. .. code-block:: console diff --git a/docs/scenarios/ml.rst b/docs/scenarios/ml.rst index baa0777..a26bd81 100644 --- a/docs/scenarios/ml.rst +++ b/docs/scenarios/ml.rst @@ -41,7 +41,7 @@ For installing the full stack, or individual packages, you can refer to the inst scikit-learn ************ -Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing. +Scikit is a free and open source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing. Because of its speed, robustness and easiness to use, it's one of the most widely-used libraries for many Machine Learning applications. diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 4cef429..d9dcc13 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -88,7 +88,7 @@ written in C. It compiles Python code to intermediate bytecode which is then interpreted by a virtual machine. CPython provides the highest level of compatibility with Python packages and C extension modules. -If you are writing open-source Python code and want to reach the widest possible +If you are writing open source Python code and want to reach the widest possible audience, targeting CPython is best. To use packages which rely on C extensions to function, CPython is your only implementation option. diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 34fc575..e6a0694 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -25,7 +25,7 @@ information. This file is the main entry point for readers of the code. An :file:`INSTALL` file is less necessary with Python. The installation instructions are often reduced to one command, such as ``pip install -module`` or ``python setup.py install`` and added to the :file:`README` +module`` or ``python setup.py install``, and added to the :file:`README` file. A :file:`LICENSE` file should *always* be present and specify the license @@ -75,7 +75,7 @@ your source repository so that rebuilding your documentation will happen automatically. When run, Sphinx_ will import your code and using Python's introspection -features it will extract all function, method and class signatures. It will +features it will extract all function, method, and class signatures. It will also extract the accompanying docstrings, and compile it all into well structured and easily readable documentation for your project. @@ -215,7 +215,7 @@ more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters. For more detailed documentation of code a popular style is the one used for the -Numpy project, often called `Numpy style`_ docstrings. While it can take up more +NumPy project, often called `NumPy style`_ docstrings. While it can take up more lines than the previous example, it allows the developer to include a lot more information about a method, function, or class. :: @@ -245,8 +245,8 @@ docstrings, making it easy to incorporate NumPy style docstrings into your project. At the end of the day, it doesn't really matter what style is used for writing -docstrings, their purpose is to serve as documentation for anyone who may need -to read or make changes to your code. As long as it is correct, understandable +docstrings; their purpose is to serve as documentation for anyone who may need +to read or make changes to your code. As long as it is correct, understandable, and gets the relevant points across then it has done the job it was designed to do. diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 125077b..677bdf8 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -205,7 +205,7 @@ will automatically write a bytecode version of that file to disk, e.g. These ``.pyc`` files should not be checked into your source code repositories. -Theoretically, this behavior is on by default, for performance reasons. +Theoretically, this behavior is on by default for performance reasons. Without these bytecode files present, Python would re-generate the bytecode every time the file is loaded. diff --git a/docs/writing/license.rst b/docs/writing/license.rst index ef7a08a..0a74f54 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -19,18 +19,18 @@ In general, these licenses tend to fall into one of two categories: 1. licenses that focus more on the user's freedom to do with the software as they please (these are the more permissive open - source licenses such as the MIT, BSD, & Apache). + source licenses such as the MIT, BSD, and Apache) 2. licenses that focus more on making sure that the code itself — including any changes made to it and distributed along with it — always remains free (these are the less permissive free software - licenses such as the GPL and LGPL). + licenses such as the GPL and LGPL) The latter are less permissive in the sense that they don't permit someone to add code to the software and distribute it without also including the source code for their changes. -To help you choose one for your project, there's a `license chooser `_, +To help you choose one for your project, there's a `license chooser `_; **use it**. **More Permissive** diff --git a/docs/writing/logging.rst b/docs/writing/logging.rst index 8d5dae9..5ea058e 100644 --- a/docs/writing/logging.rst +++ b/docs/writing/logging.rst @@ -58,7 +58,7 @@ hierarchy of loggers using dot notation, so using ``__name__`` ensures no name collisions. Here is an example of best practice from the `requests source`_ -- place -this in your ``__init__.py`` +this in your ``__init__.py``: .. code-block:: python @@ -83,7 +83,7 @@ There are at least three ways to configure a logger: - Using an INI-formatted file: - **Pro**: possible to update configuration while running using the function :func:`logging.config.listen` to listen on a socket. - - **Con**: less control (*e.g.* custom subclassed filters or loggers) + - **Con**: less control (e.g. custom subclassed filters or loggers) than possible when configuring a logger in code. - Using a dictionary or a JSON-formatted file: - **Pro**: in addition to updating while running, it is possible to load diff --git a/docs/writing/reading.rst b/docs/writing/reading.rst index a165fc1..ad67ea3 100644 --- a/docs/writing/reading.rst +++ b/docs/writing/reading.rst @@ -25,7 +25,7 @@ reading. Each one of these projects is a paragon of Python coding. best intentions in mind. - `Diamond `_ - Diamond is a python daemon that collects metrics + Diamond is a Python daemon that collects metrics and publishes them to Graphite or other backends. It is capable of collecting CPU, memory, network, I/O, load, and disk metrics. Additionally, it features an API for implementing custom collectors @@ -36,7 +36,7 @@ reading. Each one of these projects is a paragon of Python coding. applications and has become one of the most advanced WSGI utility modules. It includes a powerful debugger, full-featured request and response objects, HTTP utilities to handle entity tags, cache control headers, HTTP dates, - cookie handling, file uploads, a powerful URL routing system and a bunch + cookie handling, file uploads, a powerful URL routing system, and a bunch of community-contributed addon modules. - `Requests `_ @@ -49,4 +49,4 @@ reading. Each one of these projects is a paragon of Python coding. .. todo:: Include code examples of exemplary code from each of the projects listed. Explain why it is excellent code. Use complex examples. -.. todo:: Explain techniques to rapidly identify data structures, algorithms and determine what the code is doing. +.. todo:: Explain techniques to rapidly identify data structures and algorithms and determine what the code is doing. diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 663605f..b9e83e7 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -211,7 +211,7 @@ I highly recommend the latter. Requiring a developer to run codebase also requires them to have an isolated environment setup for each instance of the codebase. -To give the individual tests import context, create a tests/context.py +To give the individual tests import context, create a ``tests/context.py`` file: :: @@ -247,8 +247,8 @@ Makefile If you look at most of my projects or any Pocoo project, you'll notice a -Makefile laying around. Why? These projects aren't written in C... In -short, make is a incredibly useful tool for defining generic tasks for +Makefile lying around. Why? These projects aren't written in C... In +short, make is an incredibly useful tool for defining generic tasks for your project. **Sample Makefile:** @@ -334,7 +334,7 @@ include: - Multiple and messy circular dependencies: if your classes Table and Chair in :file:`furn.py` need to import Carpenter from :file:`workers.py` to answer a question such as ``table.isdoneby()``, - and if conversely the class Carpenter needs to import Table and Chair, + and if conversely the class Carpenter needs to import Table and Chair to answer the question ``carpenter.whatdo()``, then you have a circular dependency. In this case you will have to resort to fragile hacks such as using import statements inside @@ -402,7 +402,7 @@ If you'd like you could name your module :file:`my_spam.py`, but even our friend the underscore should not be seen often in module names. However, using other characters (spaces or hyphens) in module names will prevent importing (- is the subtract operator), so try to keep module names short so there is -no need to separate words. And, most of all, don't namespace with underscores, use submodules instead. +no need to separate words. And, most of all, don't namespace with underscores; use submodules instead. .. code-block:: python @@ -473,7 +473,7 @@ typing. As mentioned in the :ref:`code_style` section, readability is one of the main features of Python. Readability means to avoid useless boilerplate text and -clutter, therefore some efforts are spent trying to achieve a certain level of +clutter; therefore some efforts are spent trying to achieve a certain level of brevity. But terseness and obscurity are the limits where brevity should stop. Being able to tell immediately where a class or function comes from, as in the ``modu.func`` idiom, greatly improves code readability and understandability in @@ -494,7 +494,7 @@ used to gather all package-wide definitions. A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement ``import pack.modu``. This statement will look for an -:file:`__init__.py` file in :file:`pack`, execute all of its top-level +:file:`__init__.py` file in :file:`pack` and execute all of its top-level statements. Then it will look for a file named :file:`pack/modu.py` and execute all of its top-level statements. After these operations, any variable, function, or class defined in :file:`modu.py` is available in the pack.modu @@ -549,9 +549,9 @@ programming, comes from the "state" part of the equation. In some architectures, typically web applications, multiple instances of Python processes are spawned to respond to external requests that can happen at the -same time. In this case, holding some state into instantiated objects, which +same time. In this case, holding some state in instantiated objects, which means keeping some static information about the world, is prone to concurrency -problems or race-conditions. Sometimes, between the initialization of the state +problems or race conditions. Sometimes, between the initialization of the state of an object (usually done with the ``__init__()`` method) and the actual use of the object state through one of its methods, the world may have changed, and the retained state may be outdated. For example, a request may load an item in @@ -580,7 +580,7 @@ logic (called pure functions) allow the following benefits: - Pure functions are much easier to change or replace if they need to be refactored or optimized. -- Pure functions are easier to test with unit-tests: There is less +- Pure functions are easier to test with unit tests: There is less need for complex context setup and data cleaning afterwards. - Pure functions are easier to manipulate, decorate, and pass around. @@ -622,7 +622,7 @@ clearer and thus preferred. # bar() is decorated This mechanism is useful for separating concerns and avoiding -external un-related logic 'polluting' the core logic of the function +external unrelated logic 'polluting' the core logic of the function or method. A good example of a piece of functionality that is better handled with decoration is `memoization `__ or caching: you want to store the results of an expensive function in a table and use them directly instead of recomputing @@ -874,7 +874,7 @@ like above or in cases where you are adding to an existing string, using .. note:: You can also use the :ref:`% ` formatting operator to concatenate a pre-determined number of strings besides :py:meth:`str.join` - and ``+``. However, :pep:`3101`, discourages the usage of the ``%`` operator + and ``+``. However, :pep:`3101` discourages the usage of the ``%`` operator in favor of the :py:meth:`str.format` method. .. code-block:: python diff --git a/docs/writing/style.rst b/docs/writing/style.rst index d8a8bc7..33ed1ad 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -115,7 +115,7 @@ compared to the more straightforward calls to ``send('Hello', 'World')`` and optional, and evaluate to ``None`` when they are not passed another value. Calling a function with keyword arguments can be done in multiple ways in -Python, for example it is possible to follow the order of arguments in the +Python; for example, it is possible to follow the order of arguments in the definition without explicitly naming the arguments, like in ``send('Hello', 'World', 'Cthulhu', 'God')``, sending a blind carbon copy to God. It would also be possible to name arguments in another order, like in @@ -124,7 +124,7 @@ possibilities are better avoided without any strong reason to not follow the syntax that is the closest to the function definition: ``send('Hello', 'World', cc='Cthulhu', bcc='God')``. -As a side note, following `YAGNI `_ +As a side note, following the `YAGNI `_ principle, it is often harder to remove an optional argument (and its logic inside the function) that was added "just in case" and is seemingly never used, than to add a new optional argument and its logic when needed. @@ -134,7 +134,7 @@ than to add a new optional argument and its logic when needed. an extensible number of positional arguments, it can be defined with the ``*args`` constructs. In the function body, ``args`` will be a tuple of all the remaining positional arguments. For example, ``send(message, *args)`` - can be called with each recipient as an argument:``send('Hello', 'God', + can be called with each recipient as an argument: ``send('Hello', 'God', 'Mom', 'Cthulhu')``, and in the function body ``args`` will be equal to ``('God', 'Mom', 'Cthulhu')``. @@ -181,7 +181,7 @@ possible to do each of the following: * change how the Python interpreter imports modules -* it is even possible (and recommended if needed) to embed C routines in Python. +* It is even possible (and recommended if needed) to embed C routines in Python. However, all these options have many drawbacks and it is always better to use the most straightforward way to achieve your goal. The main drawback is that @@ -208,7 +208,7 @@ are all responsible users". This doesn't mean that, for example, no properties are considered private, and that no proper encapsulation is possible in Python. Rather, instead of relying -on concrete walls erected by the developers between their code and other's, the +on concrete walls erected by the developers between their code and others', the Python community prefers to rely on a set of conventions indicating that these elements should not be accessed directly. @@ -359,7 +359,7 @@ Instead, use a list comprehension: four_lists = [[] for __ in xrange(4)] -Note: Use range() instead of xrange() in Python 3 +Note: Use range() instead of xrange() in Python 3. Create a string from a list ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -462,7 +462,7 @@ group `_. PEP 8 ***** -:pep:`8` is the de-facto code style guide for Python. A high quality, +:pep:`8` is the de facto code style guide for Python. A high quality, easy-to-read version of PEP 8 is also available at `pep8.org `_. This is highly recommended reading. The entire Python community does their @@ -520,10 +520,10 @@ Conventions Here are some conventions you should follow to make your code easier to read. -Check if variable equals a constant +Check if a variable equals a constant ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You don't need to explicitly compare a value to True, or None, or 0 - you can +You don't need to explicitly compare a value to True, or None, or 0 -- you can just add it to the if statement. See `Truth Value Testing `_ for a list of what is considered false. @@ -608,7 +608,7 @@ Never remove items from a list while you are iterating through it. a.remove(i) Don't make multiple passes through the list. - + .. code-block:: python while i in a: @@ -617,7 +617,7 @@ Don't make multiple passes through the list. **Good**: Python has a few standard ways of filtering lists. -The approach you use depends on +The approach you use depends on: * Python 2.x vs. 3.x * Lists vs. iterators @@ -626,19 +626,19 @@ The approach you use depends on Python 2.x vs. 3.x :::::::::::::::::: -Starting with Python 3.0, the :py:func:`filter` function returns an iterator instead of a list. +Starting with Python 3.0, the :py:func:`filter` function returns an iterator instead of a list. Wrap it in :py:func:`list` if you truly need a list. .. code-block:: python list(filter(...)) -List comprehensions and generator expressions work the same in both 2.x and 3.x (except that comprehensions in 2.x "leak" variables into the enclosing namespace) +List comprehensions and generator expressions work the same in both 2.x and 3.x (except that comprehensions in 2.x "leak" variables into the enclosing namespace): - * comprehensions create a new list object - * generators iterate over the original list + * Comprehensions create a new list object. + * Generators iterate over the original list. -The :py:func:`filter` function +The :py:func:`filter` function: * in 2.x returns a list (use itertools.ifilter if you want an iterator) * in 3.x returns an iterator @@ -653,14 +653,14 @@ Creating a new list requires more work and uses more memory. If you a just going # comprehensions create a new list object filtered_values = [value for value in sequence if value != x] # Or (2.x) - filtered_values = filter(lambda i: i != x, sequence) + filtered_values = filter(lambda i: i != x, sequence) # generators don't create another list filtered_values = (value for value in sequence if value != x) # Or (3.x) filtered_values = filter(lambda i: i != x, sequence) # Or (2.x) - filtered_values = itertools.ifilter(lambda i: i != x, sequence) + filtered_values = itertools.ifilter(lambda i: i != x, sequence) @@ -678,7 +678,7 @@ Modifying the original list can be risky if there are other variables referencin # Or sequence[::] = filter(lambda value: value != x, sequence) - + Modifying the values in a list ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Bad**: @@ -690,26 +690,26 @@ Remember that assignment never creates a new object. If two or more variables re # Add three to all list members. a = [3, 4, 5] b = a # a and b refer to the same list object - + for i in range(len(a)): a[i] += 3 # b[i] also changes **Good**: -It's safer to create a new list object and leave the original alone. +It's safer to create a new list object and leave the original alone. .. code-block:: python a = [3, 4, 5] b = a - + # assign the variable "a" to a new list without changing "b" a = [i + 3 for i in a] # Or (Python 2.x): a = map(lambda i: i + 3, a) # Or (Python 3.x) a = list(map(lambda i: i + 3, a)) - + Use :py:func:`enumerate` keep a count of your place in the list. diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index dad2309..3b8f6e3 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -81,7 +81,7 @@ The Basics ********** -Unittest +unittest -------- :mod:`unittest` is the batteries-included test module in the Python standard @@ -170,7 +170,7 @@ functions: def test_answer(): assert func(3) == 5 -and then running the `py.test` command +and then running the `py.test` command: .. code-block:: console @@ -236,14 +236,14 @@ tox --- tox is a tool for automating test environment management and testing against -multiple interpreter configurations +multiple interpreter configurations. .. code-block:: console $ pip install tox tox allows you to configure complicated multi-parameter test matrices via a -simple ini-style configuration file. +simple INI-style configuration file. `tox `_ @@ -254,7 +254,7 @@ Unittest2 unittest2 is a backport of Python 2.7's unittest module which has an improved API and better assertions over the one available in previous versions of Python. -If you're using Python 2.6 or below, you can install it with pip +If you're using Python 2.6 or below, you can install it with pip: .. code-block:: console @@ -326,4 +326,3 @@ always returns the same result (but only for the duration of the test). Mock has many other ways you can configure it and control its behavior. `mock `_ - From 5dcd3b81dabb31a0e38c779248b5e2cc49807f51 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Mon, 17 Dec 2018 18:22:01 -0500 Subject: [PATCH 04/14] Update Anaconda links and text to reflect company name change --- docs/scenarios/scientific.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst index 6bdb1c9..634c983 100644 --- a/docs/scenarios/scientific.rst +++ b/docs/scenarios/scientific.rst @@ -140,11 +140,10 @@ out. Anaconda -------- -`Continuum Analytics `_ offers the `Anaconda -Python Distribution `_ which +The `Anaconda Python Distribution `_ includes all the common scientific Python packages as well as many packages -related to data analytics and big data. Anaconda itself is free, and -Continuum sells a number of proprietary add-ons. Free licenses for the +related to data analytics and big data. Anaconda itself is free, and a number +of proprietary add-ons are available for a fee. Free licenses for the add-ons are available for academics and researchers. Canopy From fd2a8f3e8ff91f5a3098458ea022fcbbaf4527d8 Mon Sep 17 00:00:00 2001 From: Harish Kesava Rao Date: Mon, 17 Dec 2018 21:02:21 -0600 Subject: [PATCH 05/14] Final commit --- docs/scenarios/serialization.rst | 58 +++++++++++++++++++++++++++++--- 1 file changed, 53 insertions(+), 5 deletions(-) diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst index ef4a193..5ba84fa 100644 --- a/docs/scenarios/serialization.rst +++ b/docs/scenarios/serialization.rst @@ -74,8 +74,9 @@ The repr method in Python takes a single object parameter and returns a printabl # write content to files using repr with open('/tmp/file.py') as f:f.write(repr(a)) + ast.literal_eval -________________ +---------------- The literal_eval method safely parses and evaluates an expression for a Python datatype. Supported data types are: strings, numbers, tuples, lists, dicts, booleans and None. @@ -95,6 +96,7 @@ Simple example for reading: .. code-block:: python + # Reading CSV content from a file import csv with open('/tmp/file.csv', newline='') as f: reader = csv.reader(f) @@ -105,6 +107,7 @@ Simple example for writing: .. code-block:: python + # Writing CSV content to a file import csv with open('/temp/file.csv', 'w', newline='') as f: writer = csv.writer(f) @@ -123,6 +126,7 @@ structures in Python. One such example is below. .. code-block:: python + # Reading YAML content from a file using the load method import yaml with open('/tmp/file.yaml', 'r', newline='') as f: try: @@ -144,22 +148,66 @@ Reading: .. code-block:: python + # Reading JSON content from a file import json with open('/tmp/file.json', 'r') as f: - data = json.dump(f) + data = json.load(f) Writing: .. code-block:: python + # writing JSON content to a file using the dump method import json with open('/tmp/file.json', 'w') as f: json.dump(data, f, sort_keys=True) +================= +XML (nested data) +================= -****** -Pickle -****** +XML parsing in Python is possible using the `xml` package. + +Example: + +.. code-block:: python + + # reading XML content from a file + import xml.etree.ElementTree as ET + tree = ET.parse('country_data.xml') + root = tree.getroot() + +More documentation on using the `xml.dom` and `xml.sax` packages can be found +`here `__. + + +******* +Binary +******* + +======================= +Numpy Array (flat data) +======================= + +Python's Numpy array can be used to serialize and deserialize data to and from byte representation. + +Example: + +.. code-block:: python + + import numpy as np + + # Converting Numpy array to byte format + byte_output = np.array([ [1, 2, 3], [4, 5, 6], [7, 8, 9] ]).tobytes() + + # Converting byte format back to Numpy array + array_format = np.frombuffer(byte_output) + + + +==================== +Pickle (nested data) +==================== The native data serialization module for Python is called `Pickle `_. From e6d6e47b460a2d78fe6abeec00301023e2a30555 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Tue, 18 Dec 2018 00:33:12 -0500 Subject: [PATCH 06/14] Use "Unix" instead of "UNIX" consistently --- docs/dev/env.rst | 2 +- docs/dev/pip-virtualenv.rst | 4 ++-- docs/starting/install/osx.rst | 2 +- docs/starting/install3/osx.rst | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index de67a9a..788234f 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -109,7 +109,7 @@ TextMate -------- `TextMate `_ brings Apple's approach to operating - systems into the world of text editors. By bridging UNIX underpinnings and + systems into the world of text editors. By bridging Unix underpinnings and GUI, TextMate cherry-picks the best of both worlds to the benefit of expert scripters and novice users alike. diff --git a/docs/dev/pip-virtualenv.rst b/docs/dev/pip-virtualenv.rst index 6971be8..ff0414b 100644 --- a/docs/dev/pip-virtualenv.rst +++ b/docs/dev/pip-virtualenv.rst @@ -105,7 +105,7 @@ need any configuration. When using older versions, you can configure pip in such a way that it tries to reuse already installed packages, too. -On UNIX systems, you can add the following line to your :file:`.bashrc` or +On Unix systems, you can add the following line to your :file:`.bashrc` or :file:`.bash_profile` file. .. code-block:: console @@ -124,7 +124,7 @@ add the following line to your :file:`pip.ini` file under ``[global]`` settings: download-cache = %HOME%\pip\cache -Similarly, on UNIX systems you should simply add the following line to your +Similarly, on Unix systems you should simply add the following line to your :file:`pip.conf` file under ``[global]`` settings: .. code-block:: console diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index df39fe6..6efcdaa 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -48,7 +48,7 @@ package. commandline tools by running ``xcode-select --install`` on the terminal. -While OS X comes with a large number of UNIX utilities, those familiar with +While OS X comes with a large number of Unix utilities, those familiar with Linux systems will notice one key component missing: a decent package manager. `Homebrew `_ fills this void. diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst index 82b5349..bc4ea3e 100644 --- a/docs/starting/install3/osx.rst +++ b/docs/starting/install3/osx.rst @@ -41,7 +41,7 @@ package. If you perform a fresh install of Xcode, you will also need to add the commandline tools by running ``xcode-select --install`` on the terminal. -While OS X comes with a large number of UNIX utilities, those familiar with +While OS X comes with a large number of Unix utilities, those familiar with Linux systems will notice one key component missing: a package manager. `Homebrew `_ fills this void. From a2555b98528213c000576671b0e35e0859d65e52 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Tue, 18 Dec 2018 02:32:06 -0500 Subject: [PATCH 07/14] Standardize on American English for the Guide --- docs/dev/env.rst | 2 +- docs/intro/learning.rst | 4 ++-- docs/notes/styleguide.rst | 3 ++- docs/writing/documentation.rst | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index de67a9a..9b75d25 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -252,7 +252,7 @@ pyenv of the Python interpreter to be installed at the same time. This solves the problem of having different projects requiring different versions of Python. For example, it becomes very easy to install Python 2.7 for compatibility in -one project, whilst still using Python 3.4 as the default interpreter. +one project, while still using Python 3.4 as the default interpreter. pyenv isn't just limited to the CPython versions - it will also install PyPy, anaconda, miniconda, stackless, jython, and ironpython interpreters. diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 2c1f19c..1ba8372 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -151,7 +151,7 @@ Python Koans ~~~~~~~~~~~~ Python Koans is a port of Edgecase's Ruby Koans. It uses a test-driven -approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial +approach to provide an interactive tutorial teaching basic Python concepts. By fixing assertion statements that fail in a test script, this provides sequential steps to learning Python. @@ -179,7 +179,7 @@ no previous programming experience. Learn to Program in Python with Codeacademy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A Codeacademy course for the absolute Python beginner. This free and interactive course provides and teaches the basics (and beyond) of Python programming whilst testing the user's knowledge in between progress. +A Codeacademy course for the absolute Python beginner. This free and interactive course provides and teaches the basics (and beyond) of Python programming while testing the user's knowledge in between progress. This course also features a built-in interpreter for receiving instant feedback on your learning. `Learn to Program in Python with Codeacademy `_ diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 2d036b3..8e32fd2 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -84,6 +84,8 @@ Wrap text lines at 78 characters. Where necessary, lines may exceed 78 characters, especially if wrapping would make the source text more difficult to read. +Use Standard American English, not British English. + Use of the `serial comma `_ (also known as the Oxford comma) is 100% non-optional. Any attempt to submit content with a missing serial comma will result in permanent banishment @@ -209,4 +211,3 @@ documents or large incomplete sections. .. todo:: Learn the Ultimate Answer to the Ultimate Question of Life, The Universe, and Everything - diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 34fc575..892dac1 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -182,7 +182,7 @@ comment block is a programmer's note. The docstring describes the Unlike block comments, docstrings are built into the Python language itself. This means you can use all of Python's powerful introspection capabilities to -access docstrings at runtime, compared with comments which are optimised out. +access docstrings at runtime, compared with comments which are optimized out. Docstrings are accessible from both the `__doc__` dunder attribute for almost every Python object, as well as with the built in `help()` function. From 3cf750bea1f12cb80f879e73982ee364ebcbcacb Mon Sep 17 00:00:00 2001 From: Harish Kesava Rao Date: Tue, 18 Dec 2018 07:01:38 -0600 Subject: [PATCH 08/14] Incorporated changes from style suggestions --- docs/scenarios/serialization.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst index 5ba84fa..408b59f 100644 --- a/docs/scenarios/serialization.rst +++ b/docs/scenarios/serialization.rst @@ -21,7 +21,7 @@ Flat vs. Nested data ******************** Before beginning to serialize data, it is important to identify or decide how the -data needs to be structured during data serialization - flat or nested. +data should to be structured during data serialization - flat or nested. The differences in the two styles are shown in the below examples. Flat style: @@ -42,7 +42,7 @@ Nested style: For more reading on the two styles, please see the discussion on `Python mailing list `__, `IETF mailing list `__ and -`here `__. +`in stackexchange `__. **************** Serializing Text @@ -57,7 +57,7 @@ If the data to be serialized is located in a file and contains flat data, Python repr ---- -The repr method in Python takes a single object parameter and returns a printable representation of the input +The repr method in Python takes a single object parameter and returns a printable representation of the input: .. code-block:: python @@ -79,7 +79,7 @@ ast.literal_eval ---------------- The literal_eval method safely parses and evaluates an expression for a Python datatype. -Supported data types are: strings, numbers, tuples, lists, dicts, booleans and None. +Supported data types are: strings, numbers, tuples, lists, dicts, booleans, and None. .. code-block:: python @@ -114,8 +114,8 @@ Simple example for writing: writer.writerows(iterable) -The module's contents, functions and examples can be found -`here `__. +The module's contents, functions, and examples can be found +`in the Python documentation `__. ================== YAML (nested data) @@ -178,7 +178,7 @@ Example: root = tree.getroot() More documentation on using the `xml.dom` and `xml.sax` packages can be found -`here `__. +`in the Python XML library documentation `__. ******* @@ -186,21 +186,21 @@ Binary ******* ======================= -Numpy Array (flat data) +NumPy Array (flat data) ======================= -Python's Numpy array can be used to serialize and deserialize data to and from byte representation. +Python's NumPy array can be used to serialize and deserialize data to and from byte representation. Example: .. code-block:: python - import numpy as np + import NumPy as np - # Converting Numpy array to byte format + # Converting NumPy array to byte format byte_output = np.array([ [1, 2, 3], [4, 5, 6], [7, 8, 9] ]).tobytes() - # Converting byte format back to Numpy array + # Converting byte format back to NumPy array array_format = np.frombuffer(byte_output) From 7022a9faef9b49e5b08a59ddd87b212b76f4fadf Mon Sep 17 00:00:00 2001 From: Surya Teja Reddy Valluri Date: Tue, 18 Dec 2018 22:32:01 +0530 Subject: [PATCH 09/14] Fixed typos/grammer --- docs/dev/virtualenvs.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 4d629d8..fede455 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -264,9 +264,9 @@ the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know that it's active. From now on, any package that you install using pip will be placed in the ``venv`` folder, isolated from the global Python installation. -For windows, same command which is mentioned in step 1 can be used for creation of virtual environment. But, to activate, we use the following command. +For Windows, same command which is mentioned in step 1 can be used for creation of virtual environment. But, to activate, we use the following command. -Assuming that, you are in project directory: +Assuming that you are in project directory: .. code-block:: powershell @@ -296,7 +296,7 @@ littered across your system, and its possible you'll forget their names or where they were placed. .. note:: - Python has included virtual environment module from 3.3. It works in the simliar way as mentioned above. For details: `venv `_. + Python has included venv module from 3.3. For more details: `venv `_. Other Notes ~~~~~~~~~~~ From 179493d96ca18487f4596143aa02002bdc891030 Mon Sep 17 00:00:00 2001 From: Surya Teja Reddy Valluri Date: Tue, 18 Dec 2018 22:33:59 +0530 Subject: [PATCH 10/14] small typo --- docs/dev/virtualenvs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index fede455..1919332 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -296,7 +296,7 @@ littered across your system, and its possible you'll forget their names or where they were placed. .. note:: - Python has included venv module from 3.3. For more details: `venv `_. + Python has included venv module from version 3.3. For more details: `venv `_. Other Notes ~~~~~~~~~~~ From 249f031fbb10f2f6249000c090a25e8bae09e173 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Tue, 18 Dec 2018 13:57:40 -0500 Subject: [PATCH 11/14] Fix sphinx build warnings --- docs/404.rst | 1 + docs/conf.py | 2 +- docs/scenarios/crypto.rst | 2 +- docs/scenarios/web.rst | 8 +++----- 4 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/404.rst b/docs/404.rst index ffef38e..f4fc9fc 100644 --- a/docs/404.rst +++ b/docs/404.rst @@ -1,3 +1,4 @@ +:orphan: ################# 404 — Not Found diff --git a/docs/conf.py b/docs/conf.py index 81fcc6f..974736f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -279,5 +279,5 @@ epub_exclude_files = [ todo_include_todos = True intersphinx_mapping = { - 'python': ('http://docs.python.org/', None), + 'python': ('https://docs.python.org/3', None), } diff --git a/docs/scenarios/crypto.rst b/docs/scenarios/crypto.rst index e6956d7..55cad28 100644 --- a/docs/scenarios/crypto.rst +++ b/docs/scenarios/crypto.rst @@ -48,7 +48,7 @@ GPGME bindings The `GPGME Python bindings `_ provide pythonic access to `GPG Made Easy `_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4 and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries. -A more comprehensive `GPGME Python Bindings HOWTO `_ is available with the source and a HTML version is available `here `_. Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `here `_. +A more comprehensive `GPGME Python Bindings HOWTO `_ is available with the source, and a HTML version is available `on http://files.au.adversary.org `_. Python 3 sample scripts from the examples in the HOWTO are also provided with the source and are accessible `on gnupg.org `_. Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause. diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 40b6656..b83ac0b 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -136,7 +136,7 @@ applications today. Masonite -------- -`Masonite `_ is a modern and developer centric, "batteries included", web framework. +`Masonite `_ is a modern and developer centric, "batteries included", web framework. The Masonite framework follows the MVC (Model-View-Controller) architecture pattern and is heavily inspired by frameworks such as Rails and Laravel, so if you are coming to Python from a Ruby or PHP background then you will feel right at home! @@ -170,7 +170,7 @@ WSGI Servers ************ Stand-alone WSGI servers typically use less resources than traditional web -servers and provide top performance [3]_. +servers and provide top performance [1]_. .. _gunicorn-ref: @@ -531,6 +531,4 @@ Mako is well respected within the Python web community. .. rubric:: References -.. [1] `The mod_python project is now officially dead `_ -.. [2] `mod_wsgi vs mod_python `_ -.. [3] `Benchmark of Python WSGI Servers `_ +.. [1] `Benchmark of Python WSGI Servers `_ From 97679865ac4848812c074be2094347588f887123 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Tue, 18 Dec 2018 14:01:35 -0500 Subject: [PATCH 12/14] Fix "WARNING: Title level inconsistent" --- docs/dev/virtualenvs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 11f9248..9f52ab2 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -219,7 +219,7 @@ Test your installation $ virtualenv --version Basic Usage -~~~~~~~~~~~ +----------- 1. Create a virtual environment for a project: @@ -285,7 +285,7 @@ littered across your system, and its possible you'll forget their names or where they were placed. Other Notes -~~~~~~~~~~~ +----------- Running ``virtualenv`` with the option ``--no-site-packages`` will not include the packages that are installed globally. This can be useful From dc85a33f3ac46f1c54183fbf52189004e27104f6 Mon Sep 17 00:00:00 2001 From: Surya Teja Reddy Valluri Date: Thu, 20 Dec 2018 21:34:46 +0530 Subject: [PATCH 13/14] Fixed Scripts issue --- docs/dev/virtualenvs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index e779e0e..ad929d9 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -270,7 +270,7 @@ Assuming that you are in project directory: .. code-block:: powershell - PS C:\Users\suryav> \venv\bin\activate + PS C:\Users\suryav> \venv\Scripts\activate Install packages as usual, for example: From 4e09d8aae016ed84abd36196563ef629022a8836 Mon Sep 17 00:00:00 2001 From: Harish Kesava Rao Date: Thu, 20 Dec 2018 20:05:01 -0600 Subject: [PATCH 14/14] Implemented feedback and suggestions from code review --- docs/scenarios/serialization.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/scenarios/serialization.rst b/docs/scenarios/serialization.rst index 408b59f..312327b 100644 --- a/docs/scenarios/serialization.rst +++ b/docs/scenarios/serialization.rst @@ -10,9 +10,9 @@ Data Serialization What is data serialization? *************************** -Data serialization is the concept of converting structured data into a format +Data serialization is the process of converting structured data into a format that allows it to be shared or stored in such a way that its original -structure can be recovered or reconstructed. In some cases, the secondary intention of data +structure should be recovered or reconstructed. In some cases, the secondary intention of data serialization is to minimize the size of the serialized data which then minimizes disk space or bandwidth requirements. @@ -21,7 +21,7 @@ Flat vs. Nested data ******************** Before beginning to serialize data, it is important to identify or decide how the -data should to be structured during data serialization - flat or nested. +data should be structured during data serialization - flat or nested. The differences in the two styles are shown in the below examples. Flat style: @@ -65,7 +65,7 @@ The repr method in Python takes a single object parameter and returns a printabl a = { "Type" : "A", "field1": "value1", "field2": "value2", "field3": "value3" } # the same input can also be read from a file - a = + a = open('/tmp/file.py', 'r') # returns a printable representation of the input; # the output can be written to a file as well @@ -135,7 +135,7 @@ structures in Python. One such example is below. print(ymlexcp) Documentation on the third party module can be found -`here `__. +`in the PyYAML Documentation `__. ======================= JSON file (nested data) @@ -157,7 +157,7 @@ Writing: .. code-block:: python - # writing JSON content to a file using the dump method + # Writing JSON content to a file using the dump method import json with open('/tmp/file.json', 'w') as f: json.dump(data, f, sort_keys=True)