diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..c25ce6dd2 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,191 @@ +# Contributing | Firebase Admin Python SDK + +Thank you for contributing to the Firebase community! + + - [Have a usage question?](#question) + - [Think you found a bug?](#issue) + - [Have a feature request?](#feature) + - [Want to submit a pull request?](#submit) + - [Need to get set up locally?](#local-setup) + + +## Have a usage question? + +We get lots of those and we love helping you, but GitHub is not the best place for them. Issues +which just ask about usage will be closed. Here are some resources to get help: + +- Go through the [guides](https://firebase.google.com/docs/admin/setup/) +- Read the full [API reference](https://firebase.google.com/docs/reference/admin/node/) + +If the official documentation doesn't help, try asking a question on the +[Firebase Google Group](https://groups.google.com/forum/#!forum/firebase-talk/) or one of our +other [official support channels](https://firebase.google.com/support/). + +**Please avoid double posting across multiple channels!** + + +## Think you found a bug? + +Yeah, we're definitely not perfect! + +Search through [old issues](https://github.com/firebase/firebase-admin-python/issues) before +submitting a new issue as your question may have already been answered. + +If your issue appears to be a bug, and hasn't been reported, +[open a new issue](https://github.com/firebase/firebase-admin-python/issues/new). Please use the +provided bug report template and include a minimal repro. + +If you are up to the challenge, [submit a pull request](#submit) with a fix! + + +## Have a feature request? + +Great, we love hearing how we can improve our products! Share you idea through our +[feature request support channel](https://firebase.google.com/support/contact/bugs-features/). + + +## Want to submit a pull request? + +Sweet, we'd love to accept your contribution! +[Open a new pull request](https://github.com/firebase/firebase-admin-python/pull/new/master) and fill +out the provided template. + +**If you want to implement a new feature, please open an issue with a proposal first so that we can +figure out if the feature makes sense and how it will work.** + +Make sure your changes pass our linter and the tests all pass on your local machine. +Most non-trivial changes should include some extra test coverage. If you aren't sure how to add +tests, feel free to submit regardless and ask us for some advice. + +Finally, you will need to sign our +[Contributor License Agreement](https://cla.developers.google.com/about/google-individual) +before we can accept your pull request. + + +## Need to get set up locally? + + +### Initial Setup + +Run the following commands from the command line to get your local environment set up: + +```bash +$ git clone https://github.com/firebase/firebase-admin-python.git +$ cd firebase-admin-python # go to the firebase-admin-python directory +$ pip install -U pytest # globally install pytest test framework and executor +$ pip install -U pylint # globally install pylint code quality checker +``` + +### Running Linters + +We use [pylint](https://pylint.org/) for verifying source code format, and +enforcing other Python programming best practices. Install pylint 1.6.4 or +higher using pip: + +``` +pip install -U pylint +``` + +Specify a pylint version explicitly if the above command installs an older +version: + +``` +pip install pylint==1.6.4 +``` + +Once installed, you can check the version of the installed binary by running +the following command: + +``` +pylint --version +``` + +There is a pylint configuration file (`.pylintrc`) at the root of this Git +repository. This enables you to invoke pylint directly from the command line: + +``` +pylint firebase +``` + +However, it is recommended that you use the `lint.sh` bash script to invoke +pylint. This script will run the linter on both `firebase` and the corresponding +`tests` module. It suprresses some of the noisy warnings that get generated +when running pylint on test code. Note that by default `lint.sh` will only +validate the locally modified source files. To validate all source files, +pass `all` as an argument. + +``` +./lint.sh # Lint locally modified source files +./lint.sh all # Lint all source files +``` + +Ideally you should not see any pylint errors or warnings when you run the +linter. This means source files are properly formatted, and the linter has +not found any issues. If you do observe any errors, fix them before +committing or sending a pull request. Details on how to interpret pylint +errors are available +[here](https://pylint.readthedocs.io/en/latest/user_guide/output.html). + +Our configuration files suppress the verbose reports usually generated +by pylint, and only output the detected issues. If you wish to obtain the +comprehensive reports, run pylint from command-line with the `-r` flag. + +``` +pylint -r yes firebase +``` + +### Unit Testing + +We use [pytest](http://doc.pytest.org/en/latest/) for writing and executing +unit tests. Download pytest 3.0.6 or higher using pip: + +``` +pip install -U pytest +``` + +All source files containing test code is located in the `tests/` +directory. Simply launch pytest from the root of the Git repository, or from +within the `tests/` directory to execute all test cases. + +``` +pytest +``` +Refer to the pytest [usage and invocations guide](http://doc.pytest.org/en/latest/usage.html) +to learn how to run a subset of all test cases. + +### Testing on Different Platforms + +Sometimes we may want to run unit tests in multiple environments (e.g. different +Python versions), and ensure that the SDK works as expected in each of them. +We use [tox](https://tox.readthedocs.io/en/latest/) for this purpose. Install +the latest version of tox using pip: + +``` +pip install -U tox +``` + +Now you can execute the following command from the root of the repository: + +``` +tox +``` + +This command will read a list of target environments from the `tox.ini` file +in the Git repository, and execute test cases in each of those environments. +We currently define the following target environments in `tox.ini`: + + * python 2.7 + + +### Repo Organization + +Here are some highlights of the directory structure and notable source files + +* `firebase/` - Source directory for the `firebase` module. +* `tests/` - Unit tests. + * `data/` - Provides mocks for several variables as well as mock service account keys. +* `.github/` - Contribution instructions as well as issue and pull request templates. +* `lint.sh` - Runs pylint to check for code quality. +* `.pylintrc` - Default configuration for pylint. +* `setup.py` - Python setup script for building distribution artifacts. +* `tox.ini` - Tox configuration for running tests on different environments. diff --git a/README.md b/README.md index aa57b3060..a99e7713e 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,29 @@ # Firebase Admin Python SDK -The Firebase Admin Python SDK enables server-side (backend) Python developers -to integrate [Firebase](https://firebase.google.com) into their services -and applications. Currently this SDK provides Firebase custom authentication -support. +## Table of Contents + * [Overview](#overview) + * [Documentation](#documentation) + * [License and Terms](#license-and-terms) -## Unit Testing -We use [pytest](http://doc.pytest.org/en/latest/) for writing and executing -unit tests. Download pytest 3.0.6 or higher using pip: +## Overview -``` -pip install -U pytest -``` +[Firebase](https://firebase.google.com) provides the tools and infrastructure +you need to develop apps, grow your user base, and earn money. The Firebase +Admin Python SDK enables server-side (backend) Python developers to integrate +Firebase into their services and applications. Currently this SDK provides +Firebase custom authentication support. -All source files containing test code is located in the `tests/` -directory. Simply launch pytest from the root of the Git repository, or from -within the `tests/` directory to execute all test cases. +For more information, visit the +[Firebase Admin SDK setup guide](https://firebase.google.com/docs/admin/setup/). -``` -pytest -``` -Refer to the pytest [usage and invocations guide](http://doc.pytest.org/en/latest/usage.html) -to learn how to run a subset of all test cases. +## Documentation +* [Setup Guide](https://firebase.google.com/docs/admin/setup/) -## Running Linters -We use [pylint](https://pylint.org/) for verifying source code format, and -enforcing other Python programming best practices. Install pylint 1.6.4 or -higher using pip: -``` -pip install -U pylint -``` +## License and Terms -Specify a pylint version explicitly if the above command installs an older -version: - -``` -pip install pylint==1.6.4 -``` - -Once installed, you can check the version of the installed binary by running -the following command: - -``` -pylint --version -``` - -There is a pylint configuration file (`.pylintrc`) at the root of this Git -repository. This enables you to invoke pylint directly from the command line: - -``` -pylint firebase -``` - -However, it is recommended that you use the `lint.sh` bash script to invoke -pylint. This script will run the linter on both `firebase` and the corresponding -`tests` module. It suprresses some of the noisy warnings that get generated -when running pylint on test code. Note that by default `lint.sh` will only -validate the locally modified source files. To validate all source files, -pass `all` as an argument. - -``` -./lint.sh # Lint locally modified source files -./lint.sh all # Lint all source files -``` - -Ideally you should not see any pylint errors or warnings when you run the -linter. This means source files are properly formatted, and the linter has -not found any issues. If you do observe any errors, fix them before -committing or sending a pull request. Details on how to interpret pylint -errors are available -[here](https://pylint.readthedocs.io/en/latest/user_guide/output.html). - -Our configuration files suppress the verbose reports usually generated -by pylint, and only output the detected issues. If you wish to obtain the -comprehensive reports, run pylint from command-line with the `-r` flag. - -``` -pylint -r yes firebase -``` +Your use of Firebase is governed by the +[Terms of Service for Firebase Services](https://firebase.google.com/terms/). diff --git a/setup.py b/setup.py new file mode 100644 index 000000000..f0837edf5 --- /dev/null +++ b/setup.py @@ -0,0 +1,95 @@ +"""Setup file for distribution artifacts.""" +from os import path +from setuptools import setup, find_packages + + +here = path.abspath(path.dirname(__file__)) + +long_description = ('The Firebase Admin Python SDK enables server-side (backend) Python developers ' + 'to integrate Firebase into their services and applications. Currently this ' + 'SDK provides Firebase custom authentication support.') + +setup( + name='firebase', + + # Versions should comply with PEP440. For a discussion on single-sourcing + # the version across setup.py and the project code, see + # https://packaging.python.org/en/latest/single_source_version.html + version='0.0.1', + + description='Firebase Admin Python SDK', + long_description=long_description, + + # The project's main homepage. + url='https://github.com/pypa/sampleproject', + + # Author details + author='Firebase Team', + author_email='firebase-talk@googlegroups.com', + + # Choose your license + license='Apache Software License 2.0', + + # See https://pypi.python.org/pypi?%3Aaction=list_classifiers + classifiers=[ + # How mature is this project? Common values are + # 3 - Alpha + # 4 - Beta + # 5 - Production/Stable + 'Development Status :: 3 - Alpha', + + # Indicate who your project is intended for + 'Intended Audience :: Developers', + 'Topic :: Software Development :: Build Tools', + + # Pick your license as you wish (should match "license" above) + 'License :: OSI Approved :: Apache Software License', + + # Specify the Python versions you support here. In particular, ensure + # that you indicate whether you support Python 2, Python 3 or both. + 'Programming Language :: Python :: 2', + 'Programming Language :: Python :: 2.7', + ], + + # What does your project relate to? + keywords='firebase cloud development', + + packages=find_packages(exclude=['tests']), + + # List run-time dependencies here. These will be installed by pip when + # your project is installed. For an analysis of "install_requires" vs pip's + # requirements files see: + # https://packaging.python.org/en/latest/requirements.html + install_requires=['oauth2client'], + + # List additional groups of dependencies here (e.g. development + # dependencies). You can install these using the following syntax, + # for example: + # $ pip install -e .[dev,test] + #extras_require={ + # 'dev': ['check-manifest'], + # 'test': ['coverage'], + #}, + + # If there are data files included in your packages that need to be + # installed, specify them here. If using Python 2.6 or less, then these + # have to be included in MANIFEST.in as well. + #package_data={ + # 'sample': ['package_data.dat'], + #}, + + # Although 'package_data' is the preferred approach, in some case you may + # need to place data files outside of your packages. See: + # http://docs.python.org/3.4/distutils/setupscript.html#installing-additional-files # noqa + # In this case, 'data_file' will be installed into '/my_data' + #data_files=[('my_data', ['data/data_file'])], + + # To provide executable scripts, use entry points in preference to the + # "scripts" keyword. Entry points provide cross-platform support and allow + # pip to create the appropriate form of executable for the target platform. + #entry_points={ + # 'console_scripts': [ + # 'sample=sample:main', + # ], + #}, +) diff --git a/tox.ini b/tox.ini new file mode 100644 index 000000000..b27c99c4a --- /dev/null +++ b/tox.ini @@ -0,0 +1,13 @@ +# Tox (https://tox.readthedocs.io/) is a tool for running tests +# in multiple virtualenvs. This configuration file will run the +# test suite on all supported python versions. To use it, "pip install tox" +# and then run "tox" from this directory. + +[tox] +envlist = py27 + +[testenv] +commands = pytest +deps = + pytest + oauth2client