diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 0000000..476592b --- /dev/null +++ b/.coveragerc @@ -0,0 +1,9 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +[run] +source = nutritionparser diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..336fc45 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,41 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +# http://editorconfig.org + +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 4 +indent_style = space +insert_final_newline = true +trim_trailing_whitespace = true + +# Python files +[*.py] +indent_size = 4 +# isort plugin configuration +multi_line_output = 2 +default_section = THIRDPARTY + +# RST files (used by sphinx) +[*.rst] +indent_size = 4 + +# CSS, HTML, JS, JSON, YML +[*.{css,html,js,json,yml}] +indent_size = 2 + +# Matches the exact files either package.json or .travis.yml +[{package.json,.travis.yml}] +indent_size = 2 + +# Dockerfile +[Dockerfile] +indent_size = 4 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7cdbc25 --- /dev/null +++ b/.gitignore @@ -0,0 +1,60 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] + +# C extensions +*.so + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.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 +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*,cover + +# Translations +*.mo +*.pot + +# Django stuff: +*.log + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Ignore the data directory +data/ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..bec3749 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,44 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +sudo: false + +language: python + +python: + - "3.4" + - "3.3" + - "2.7" + - "pypy" + +cache: + - pip + +install: + # Install test dependencies + - "travis_retry pip install coveralls pep257 Sphinx twine wheel" + - "travis_retry pip install pytest pytest-pep8 pytest-cov pytest-cache" + - "travis_retry pip install ." + - "mkdir data && cd data && wget https://www.ars.usda.gov/SP2UserFiles/Place/12354500/Data/SR27/dnload/sr27asc.zip && unzip sr27asc.zip && cd .." + +script: ./run-tests.sh + +after_success: + - coveralls + +notifications: + email: false + +deploy: + provider: pypi + user: lnielsen + password: + secure: CHANGEME + distributions: "sdist bdist_wheel" + on: + tags: true + python: "2.7" diff --git a/AUTHORS.rst b/AUTHORS.rst new file mode 100644 index 0000000..cf38d36 --- /dev/null +++ b/AUTHORS.rst @@ -0,0 +1,4 @@ +Credits +======= + +* Lars Holm Nielsen diff --git a/CHANGES.rst b/CHANGES.rst new file mode 100644 index 0000000..67247ed --- /dev/null +++ b/CHANGES.rst @@ -0,0 +1,8 @@ +.. :changes: + +Changes +======= + +0.1.0 (2015-08-22) + +* Initial public release diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..96d717f --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,113 @@ +============ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given. + +Types of Contributions +---------------------- + +Report Bugs +~~~~~~~~~~~ + +Report bugs at https://github.com/lnielsen/nutritionparser/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" +is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "feature" +is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +Nutrition Parser could always use more documentation, whether as part of the +official Nutrition Parser docs, in docstrings, or even on the web in blog posts, +articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at https://github.com/lnielsen/nutritionparser/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `nutritionparser` for local development. + +1. Fork the `nutritionparser` repo on GitHub. +2. Clone your fork locally: + + .. code-block:: console + + $ git clone git@github.com:your_name_here/nutritionparser.git + +3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: + + .. code-block:: console + + $ mkvirtualenv nutritionparser + $ cd nutritionparser/ + $ pip install -r requirements.txt + +4. Create a branch for local development: + + .. code-block:: console + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +5. When you're done making changes, check that your changes pass tests, including testing other Python versions with tox: + + .. code-block:: console + + $ ./run-tests.sh + $ tox + + The tests will provide you with test coverage and also check PEP8 + (code style), PEP257 (documentation), flake8 as well as build the Sphinx + documentation and run doctests in the documentation. + +6. Commit your changes and push your branch to GitHub: + + .. code-block:: console + + $ git add . + $ git commit -s -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + +7. Submit a pull request through the GitHub website. + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests and must not decrease test coverage. +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in README.rst. +3. The pull request should work for Python 2.6, 2.7, 3.3, and 3.4, and for PyPy. Check + https://travis-ci.org/lnielsen/nutritionparser/pull_requests + and make sure that the tests pass for all supported Python versions. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..347ad18 --- /dev/null +++ b/LICENSE @@ -0,0 +1,34 @@ +Nutrition Parser is free software; you can redistribute it and/or +modify it under the terms of the Revised BSD License; see LICENSE +file for more details. + +Copyright (C) 2015, Lars Holm Nielsen +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..3be945c --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,22 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +include AUTHORS.rst +include CHANGES.rst +include CONTRIBUTING.rst +include LICENSE +include README.rst +include .coveragerc +include run-tests.sh + +recursive-include tests * +recursive-exclude * __pycache__ +recursive-exclude * *.py[co] + +recursive-include docs *.rst conf.py Makefile diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b87422f --- /dev/null +++ b/README.rst @@ -0,0 +1,16 @@ +================== + Nutrition Parser +================== + +.. image:: https://travis-ci.org/lnielsen/nutritionparser.svg?branch=master + :target: https://travis-ci.org/lnielsen/nutritionparser + +.. image:: https://coveralls.io/repos/lnielsen/nutritionparser/badge.svg?branch=master + :target: https://coveralls.io/r/lnielsen/nutritionparser + +.. image:: https://img.shields.io/pypi/v/nutritionparser.svg + :target: https://pypi.python.org/pypi/nutritionparser + + +Nutrition Parser is a package for parsing USDA National Nutrient Database +files. diff --git a/RELEASE-NOTES.rst b/RELEASE-NOTES.rst new file mode 100644 index 0000000..37e88e3 --- /dev/null +++ b/RELEASE-NOTES.rst @@ -0,0 +1,30 @@ +========================= + Nutrition Parser v0.1.0 +========================= + +Nutrition Parser v0.1.0 was released on 2015-08-22 + +About +----- + +Nutrition Parser is a small package for parsing USDA National Nutrient Database +files. + +Installation +------------ + + $ pip install nutritionparser + +What's new +---------- + +Documentation +------------- + + http://pythonhosted.org/nutritionparser/ + +Website +------- + + https://github.com/lnielsen/nutritionparser + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..817ce7e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/nutritionparser.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/nutritionparser.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/nutritionparser" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/nutritionparser" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..69ddb08 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,7 @@ +API Docs +======== + +.. autofunction:: nutritionparser.reader.reader + +.. autodata:: nutritionparser.reader.sr27fields + diff --git a/docs/authors.rst b/docs/authors.rst new file mode 100644 index 0000000..8047142 --- /dev/null +++ b/docs/authors.rst @@ -0,0 +1,7 @@ +.. include:: ../CHANGES.rst + +License +======= +.. include:: ../LICENSE + +.. include:: ../AUTHORS.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100755 index 0000000..15f75e2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,312 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +# +# nutritionparser documentation build configuration file, created by +# sphinx-quickstart on Tue Jul 9 22:26:36 2013. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import re + +import sphinx.environment +from docutils.utils import get_source_line + +def _warn_node(self, msg, node): + if not msg.startswith('nonlocal image URI found:'): + self._warnfunc(msg, '%s:%s' % get_source_line(node)) + +sphinx.environment.BuildEnvironment.warn_node = _warn_node + +# If extensions (or modules to document with autodoc) are in another +# directory, add these directories to sys.path here. If the directory is +# relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# Get the project root dir, which is the parent dir of this +cwd = os.getcwd() +project_root = os.path.dirname(cwd) + +# Insert the project root dir as the first element in the PYTHONPATH. +# This lets us ensure that the source package is imported, and that its +# version is used. +sys.path.insert(0, project_root) + +# -- General configuration --------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Nutrition Parser' +copyright = u'2015, Lars Holm Nielsen' + +# The version info for the project you're documenting, acts as replacement +# for |version| and |release|, also used in various other places throughout +# the built documents. +# +# The short X.Y version. +# Get the version string. Cannot be done with import! +with open(os.path.join('..', 'nutritionparser', 'version.py'), 'rt') as f: + version = re.search( + '__version__\s*=\s*"(?P.*)"\n', + f.read() + ).group('version') + +# The full version, including alpha/beta/rc tags. +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to +# some non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built +# documents. +#keep_warnings = False + + +# -- Options for HTML output ------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a +# theme further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + 'description': 'Nutrition Parser is a package for parsing USDA National Nutrient Database files.', + 'github_user': 'lnielsen', + 'github_repo': 'nutritionparser', + 'github_button': False, + 'github_banner': True, + 'show_powered_by': False, + 'extra_nav_links' : { + 'nutritionparser@GitHub' : 'http://github.com/lnielsen/nutritionparser/', + 'nutritionparser@PyPI' : 'http://pypi.python.org/pypi/nutritionparser/', + } +} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as +# html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the +# top of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon +# of the docs. This file should be a Windows icon file (.ico) being +# 16x16 or 32x32 pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) +# here, relative to this directory. They are copied after the builtin +# static files, so a file named "default.css" will overwrite the builtin +# "default.css". +# html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + +# Additional templates that should be rendered to pages, maps page names +# to template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. +# Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. +# Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages +# will contain a tag referring to it. The value of this option +# must be the base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'nutritionparserdoc' + + +# -- Options for LaTeX output ------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + #'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', 'nutritionparser.tex', + u'Nutrition Parser Documentation', + u'Lars Holm Nielsen', 'manual'), +] + +# The name of an image file (relative to this directory) to place at +# the top of the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings +# are parts, not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output ------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'nutritionparser', + u'Nutrition Parser Documentation', + [u'Lars Holm Nielsen'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ---------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'nutritionparser', + u'Nutrition Parser Documentation', + u'Lars Holm Nielsen', + 'nutritionparser', + 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..e582053 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..5ad8a04 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,37 @@ +.. include:: ../README.rst + +User's Guide +------------ + +This part of the documentation will show you how to get started in using Nutrition Parser + +.. toctree:: + :maxdepth: 2 + + installation + usage + + +API Reference +------------- + +If you are looking for information on a specific function, class or method, +this part of the documentation is for you. + +.. toctree:: + :maxdepth: 2 + + api + +Additional Notes +---------------- + +Notes on how to contribute, legal information and changes are here for the +interested. + +.. toctree:: + :maxdepth: 1 + + contributing + authors + diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..3cc5a8e --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,23 @@ +============ +Installation +============ + +At the command line: + +.. code-block:: console + + $ pip install nutritionparser + +Or, if you have virtualenvwrapper installed: + +.. code-block:: console + + $ mkvirtualenv nutritionparser + $ pip install nutritionparser + +If you plan running the tests or building documentation you should install +the developer requirements: + +.. code-block:: console + + $ pip install -r requirements.txt diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..a066940 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,5 @@ +======= + Usage +======= + +.. automodule:: nutritionparser diff --git a/nutritionparser/__init__.py b/nutritionparser/__init__.py new file mode 100755 index 0000000..1c50a64 --- /dev/null +++ b/nutritionparser/__init__.py @@ -0,0 +1,98 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +r"""Nutrition Parser parses USDA National Nutrient Database files. + +Getting the data +---------------- +First, download the actual data from USDA's website at +http://www.ars.usda.gov/Services/docs.htm?docid=24912 (currently only release +SR27 is supported). Download the ASCII version. + +.. code-block:: console + + $ mkdir data + $ cd data + $ wget https://www.ars.usda.gov/SP2UserFiles/Place/12354500/Data/\\ + > SR27/dnload/sr27asc.zip + $ unzip sr27asc.zip + $ ls -1 + DATA_SRC.txt + DATSRCLN.txt + DERIV_CD.txt + FD_GROUP.txt + FOOD_DES.txt + FOOTNOTE.txt + LANGDESC.txt + LANGUAL.txt + NUTR_DEF.txt + NUT_DATA.txt + SRC_CD.txt + WEIGHT.txt + sr27_doc.pdf + sr27asc.zip + +The ``.txt`` files are actually CSV files with special quote and delimiter +characters. The included PDF file contains full documentation of all fields +in the CSV files. + +Parsing the data +---------------- +Parsing a data file is easy, just import the ``reader`` and point it to the +data file you want to parse: + + >>> from nutritionparser import reader + >>> for l in reader('data/FD_GROUP.txt'): + ... print(l['FdGrp_Desc']) + Dairy and Egg Products + Spices and Herbs + Baby Foods + Fats and Oils + Poultry Products + Soups, Sauces, and Gravies + Sausages and Luncheon Meats + Breakfast Cereals + Fruits and Fruit Juices + Pork Products + Vegetables and Vegetable Products + Nut and Seed Products + Beef Products + Beverages + Finfish and Shellfish Products + Legumes and Legume Products + Lamb, Veal, and Game Products + Baked Products + Sweets + Cereal Grains and Pasta + Fast Foods + Meals, Entrees, and Side Dishes + Snacks + American Indian/Alaska Native Foods + Restaurant Foods + +You can also inspect the fields available for each file: + + >>> from nutritionparser import sr27fields + >>> for f in sr27fields['FOOD_DES.txt']: + ... print(f) + NDB_No + FdGrp_Cd + ... + FdGrp_Desc + +Full documentation for each fields is available in the included POF file of the +data. +""" + +from __future__ import absolute_import, unicode_literals, print_function + +from .reader import reader, sr27fields +from .version import __version__ + +__all__ = ('__version__', 'reader', 'sr27fields') diff --git a/nutritionparser/reader.py b/nutritionparser/reader.py new file mode 100755 index 0000000..91b4658 --- /dev/null +++ b/nutritionparser/reader.py @@ -0,0 +1,160 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +"""nutritionparser module.""" + +from __future__ import absolute_import, unicode_literals, print_function + +import csv +import io +import sys +from os.path import basename + + +PY2 = sys.version_info[0] == 2 + +delimiter = '~'.encode('ascii') if PY2 else "^" +quotechar = '~'.encode('ascii') if PY2 else '~' + + +def utf8_encoder(csv_data): + """Encode Unicode to UTF8. + + Ensures that Python 2 CSV module can handle the data. + """ + for line in csv_data: + yield line.encode('utf-8') if PY2 else line + + +def reader(filepath, fields=None): + """Read CSV files from USDA National Nutrient Database. + + :param filepath: Path to a USDA data file. + :param fields: Fields in data file. Default: ``None`` (i.e use SR27 field + names). + """ + filename = basename(filepath) + + if fields is None: + fields = sr27fields + + fieldnames = fields[filename] + + with io.open(filepath, newline='\r\n', encoding='iso-8859-1') as f: + reader = csv.DictReader( + utf8_encoder(f), + fieldnames=fieldnames, + delimiter=delimiter, + quotechar=quotechar + ) + for row in reader: + yield row + + +sr27fields = { + 'FOOD_DES.txt': [ + 'NDB_No', + 'FdGrp_Cd', + 'Long_Desc', + 'Shrt_Desc', + 'ComName', + 'ManufacName', + 'Survey', + 'Ref_desc', + 'Refuse', + 'SciName', + 'N_Factor', + 'Pro_Factor', + 'Fat_Factor', + 'CHO_Factor', + 'FdGrp_Cd', + 'FdGrp_Desc', + ], + 'FD_GROUP.txt': [ + 'FdGrp_Cd', + 'FdGrp_Desc', + ], + 'LANGUAL.txt': [ + 'NDB_No', + 'Factor_Code', + ], + 'LANGDESC.txt': [ + 'Factor_Code', + 'Description', + ], + 'NUT_DATA.txt': [ + 'NDB_No', + 'Nutr_No', + 'Nutr_Val', + 'Num_Data_Pts', + 'Std_Error', + 'Src_Cd', + 'Deriv_Cd', + 'Ref_NDB_No', + 'Add_Nutr_Mark', + 'Num_Studies', + 'Min', + 'Max', + 'DF', + 'Low_EB', + 'Up_EB', + 'Stat_cmt', + 'AddMod_Date', + 'CC', + ], + 'NUTR_DEF.txt': [ + 'Nutr_No', + 'Units', + 'Tagname', + 'NutrDesc', + 'Num_Dec', + 'SR_Order', + ], + 'SRC_CD.txt': [ + 'Src_Cd', + 'SrcCd_Desc', + ], + 'DERIV_CD.txt': [ + 'Deriv_Cd', + 'Deriv_Desc', + ], + 'WEIGHT.txt': [ + 'NDB_No', + 'Seq', + 'Amount', + 'Msre_Desc', + 'Gm_Wgt', + 'Num_Data_Pts', + 'Std_Dev', + ], + 'FOOTNOTE.txt': [ + 'NDB_No', + 'Footnt_No', + 'Footnt_Typ', + 'Nutr_No', + 'Footnt_Txt', + ], + 'DATSRCLN.txt': [ + 'NDB_No', + 'Nutr_No', + 'DataSrc_ID', + ], + 'DATA_SRC.txt': [ + 'DataSrc_ID', + 'Authors', + 'Title', + 'Year', + 'Journal', + 'Vol_City', + 'Issue_State', + 'Start_Page', + 'End_Page', + ], +} +"""SR27 field names.""" diff --git a/nutritionparser/version.py b/nutritionparser/version.py new file mode 100644 index 0000000..3f4568d --- /dev/null +++ b/nutritionparser/version.py @@ -0,0 +1,19 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +"""Version information for Nutrition Parser. + +This file is imported by ``nutritionparser.__init__``, and parsed by +``setup.py`` as well as ``docs/conf.py``. +""" + +# Do not change the format of this next line. Doing so risks breaking +# setup.py and docs/conf.py + +__version__ = "0.1.0.dev20150822" diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 0000000..40a939a --- /dev/null +++ b/pytest.ini @@ -0,0 +1,9 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +[pytest] +addopts = --clearcache --pep8 --ignore=docs --cov=nutritionparser --cov-report=term-missing tests nutritionparser diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..1a0f99d --- /dev/null +++ b/requirements.txt @@ -0,0 +1,19 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +# Requirements file for development installs +-e . + +# Requirements for building documentation, running tests and making releases +Sphinx +wheel +twine +pep257 +tox +sphinx-pypi-upload diff --git a/run-tests.sh b/run-tests.sh new file mode 100755 index 0000000..61f9885 --- /dev/null +++ b/run-tests.sh @@ -0,0 +1,11 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +pep257 nutritionparser && \ +sphinx-build -qnNW docs docs/_build/html && \ +python setup.py test && \ +sphinx-build -qnNW -b doctest docs docs/_build/doctest diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..e79fd75 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,14 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +[wheel] +universal = 1 + +[build_sphinx] +source-dir = docs/ +build-dir = docs/_build +all_files = 1 diff --git a/setup.py b/setup.py new file mode 100755 index 0000000..d1591c0 --- /dev/null +++ b/setup.py @@ -0,0 +1,113 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + +"""Nutrition Parser parses USDA National Nutrient Database files.""" + +import os +import re +import sys + +from setuptools import setup +from setuptools.command.test import test as TestCommand + + +class PyTest(TestCommand): + + """Integration of PyTest with setuptools.""" + + user_options = [('pytest-args=', 'a', 'Arguments to pass to py.test')] + + def initialize_options(self): + """Initialize options.""" + TestCommand.initialize_options(self) + try: + from ConfigParser import ConfigParser + except ImportError: + from configparser import ConfigParser + config = ConfigParser() + config.read("pytest.ini") + self.pytest_args = config.get("pytest", "addopts").split(" ") + + def finalize_options(self): + """Finalize options.""" + TestCommand.finalize_options(self) + self.test_args = [] + self.test_suite = True + + def run_tests(self): + """Run tests.""" + # import here, cause outside the eggs aren't loaded + import pytest + import _pytest.config + pm = _pytest.config.get_plugin_manager() + pm.consider_setuptools_entrypoints() + errno = pytest.main(self.pytest_args) + sys.exit(errno) + + +# Get the version string. Cannot be done with import! +with open(os.path.join('nutritionparser', 'version.py'), 'rt') as f: + version = re.search( + '__version__\s*=\s*"(?P.*)"\n', + f.read() + ).group('version') + + +with open('README.rst') as readme_file: + readme = readme_file.read() + +with open('CHANGES.rst') as history_file: + history = history_file.read().replace('.. :changes:', '') + +requirements = [ +] + +extras_requirements = {} + +test_requirements = [ + 'pytest-cache>=1.0', + 'pytest-cov>=1.8.0', + 'pytest-pep8>=1.0.6', + 'pytest>=2.6.1', + 'coverage<4.0a1', +] + +setup( + name='nutritionparser', + version=version, + description=__doc__, + long_description=readme + '\n\n' + history, + author="Lars Holm Nielsen", + author_email='lars@hankat.dk', + url='https://github.com/lnielsen/nutritionparser', + packages=[ + 'nutritionparser', + ], + package_dir={'nutritionparser': + 'nutritionparser'}, + include_package_data=True, + install_requires=requirements, + extras_require=extras_requirements, + license="BSD", + zip_safe=False, + keywords='nutritionparser', + classifiers=[ + 'Intended Audience :: Developers', + 'License :: OSI Approved :: BSD License', + 'Natural Language :: English', + "Programming Language :: Python :: 2", + 'Programming Language :: Python :: 2.6', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3.3', + 'Programming Language :: Python :: 3.4', + ], + tests_require=test_requirements, + cmdclass={'test': PyTest}, +) diff --git a/tests/test_nutritionparser.py b/tests/test_nutritionparser.py new file mode 100755 index 0000000..eeed2fd --- /dev/null +++ b/tests/test_nutritionparser.py @@ -0,0 +1,28 @@ +# -*- coding: utf-8 -*- +# +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. + + +"""Tests for `nutritionparser` module.""" + +import os + +from nutritionparser import reader, sr27fields + + +def test_nutritionparser(): + """Test nutritionparser.""" + # Test if data has been downloaded + assert os.path.exists("data/FOOD_DES.txt") + + for f in sr27fields.keys(): + for i, data in enumerate(reader("data/{0}".format(f))): + if i == 0: + for field in sr27fields[f]: + assert field in data + assert isinstance(data, dict) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..99b08ad --- /dev/null +++ b/tox.ini @@ -0,0 +1,28 @@ +# This file is part of Nutrition Parser +# Copyright (C) 2015 Lars Holm Nielsen. +# +# Nutrition Parser is free software; you can redistribute it and/or +# modify it under the terms of the Revised BSD License; see LICENSE +# file for more details. +[tox] +envlist = py27, py33, py34 + +[testenv] +setenv = + PYTHONPATH = {toxinidir}:{toxinidir}/nutritionparser +commands = + python setup.py test + + +# See https://wiki.python.org/moin/TestPyPI +[testenv:release] +deps = + twine >= 1.4.0 + wheel + Sphinx + sphinx-pypi-upload +commands = + /bin/rm -Rf {toxinidir}/dist + {envpython} setup.py clean --all + {envpython} setup.py sdist bdist_wheel build_sphinx + twine upload -r pypi {posargs} dist/*