pax_global_header00006660000000000000000000000064147157024240014520gustar00rootroot0000000000000052 comment=86a1ea5aafbb412d93935e8aeadf57e516751008 django-waffle-4.2.0/000077500000000000000000000000001471570242400142275ustar00rootroot00000000000000django-waffle-4.2.0/.github/000077500000000000000000000000001471570242400155675ustar00rootroot00000000000000django-waffle-4.2.0/.github/dependabot.yml000066400000000000000000000004661471570242400204250ustar00rootroot00000000000000# Please see the documentation for all configuration options: # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file version: 2 updates: - package-ecosystem: "github-actions" directory: "/" schedule: interval: "monthly" django-waffle-4.2.0/.github/stale.yml000066400000000000000000000007621471570242400174270ustar00rootroot00000000000000daysUntilStale: 30 daysUntilClose: 14 exemptLabels: - security - pinned - pr-wanted staleLabel: stale markComment: > This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. closeComment: > This issue has been closed as stale because it has not had any recent activity. Please feel free to re-open if the issue is still relevant. Thank you for your contributions! django-waffle-4.2.0/.github/workflows/000077500000000000000000000000001471570242400176245ustar00rootroot00000000000000django-waffle-4.2.0/.github/workflows/python-package.yml000066400000000000000000000071451471570242400232700ustar00rootroot00000000000000# This workflow will install Python dependencies, run tests and lint with a variety of Python versions # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions name: Python package on: push: branches: [ master ] tags: - v* pull_request: branches: [ master ] jobs: test: runs-on: ubuntu-latest strategy: fail-fast: false matrix: python-version: [ 3.8, 3.9, '3.10', 3.11, 3.12, 3.13 ] steps: - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ matrix.python-version }}-pip-${{ hashFiles('**/requirements.txt') }} restore-keys: | ${{ matrix.python-version }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip python -m pip install tox-gh-actions if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - name: Test run: | tox lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 - uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ matrix.python-version }}-pip-${{ hashFiles('**/requirements.txt') }} restore-keys: | ${{ matrix.python-version }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip python -m pip install tox-gh-actions if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - name: Lint run: ruff check --output-format=github . typecheck: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 - uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ matrix.python-version }}-pip-${{ hashFiles('**/requirements.txt') }} restore-keys: | ${{ matrix.python-version }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip python -m pip install tox-gh-actions if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - name: Type-check run: | tox -e typecheck i18n: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 - uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ matrix.python-version }}-pip-${{ hashFiles('**/requirements.txt') }} restore-keys: | ${{ matrix.python-version }}-pip- - name: Install gettext run: | sudo apt-get install -y gettext-base gettext - name: Install dependencies run: | python -m pip install --upgrade pip python -m pip install django if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - name: i18n validation run: | tox -e i18n release-production: # Only upload if a tag is pushed (otherwise just build & check) if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags') runs-on: ubuntu-latest needs: [test, lint, i18n] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 - uses: casperdcl/deploy-pypi@v2 with: password: ${{ secrets.PYPI_API_TOKEN }} build: true django-waffle-4.2.0/.gitignore000066400000000000000000000002511471570242400162150ustar00rootroot00000000000000*.py[oc] *.swp build dist *.egg-info *test.db .coverage .idea/ *.iml .project .pydevproject .settings .tox/ .DS_Store docs/_* # Visual Studio Code config files .vscode django-waffle-4.2.0/.pre-commit-config.yaml000066400000000000000000000003771471570242400205170ustar00rootroot00000000000000repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: 'v5.0.0' hooks: - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.7.3 hooks: - id: ruff django-waffle-4.2.0/.readthedocs.yaml000066400000000000000000000013131471570242400174540ustar00rootroot00000000000000# Read the Docs configuration file for Sphinx projects # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # Required version: 2 # Set the OS, Python version and other tools you might need build: os: ubuntu-22.04 tools: python: "3.12" # Build documentation in the "docs/" directory with Sphinx sphinx: configuration: docs/conf.py # Optionally build your docs in additional formats such as PDF and ePub # formats: # - pdf # - epub # Optional but recommended, declare the Python requirements required # to build your documentation # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html # python: # install: # - requirements: docs/requirements.txt django-waffle-4.2.0/.tx/000077500000000000000000000000001471570242400147405ustar00rootroot00000000000000django-waffle-4.2.0/.tx/config000066400000000000000000000003401471570242400161250ustar00rootroot00000000000000[main] host = https://www.transifex.com [django-waffle.django-po] file_filter = waffle/locale//LC_MESSAGES/django.po minimum_perc = 0 source_file = waffle/locale/en_US/LC_MESSAGES/django.po source_lang = en type = PO django-waffle-4.2.0/CHANGES000066400000000000000000000160311471570242400152230ustar00rootroot00000000000000================ Waffle Changelog ================ v4.2.0 ====== - Joined Jazzband (https://jazzband.co/) - Linting improvements and cleanups - Added support for Django 5.0 and 5.1 - Added support for Python 3.13 v4.1.0 ====== - Updated `is_active_for_user` method to account for `everyone` option - Added `--testing` option to waffle_flag management command v4.0.0 ====== - Added support for Django 4.2 and Python 3.11 - Dropped support for Python 3.7 - Added type hints v3.0.0 ====== - Added support for pluggable Sample and Switch models - Removed support EOL Python versions - Removed support for EOL Django versions v2.7.0 ====== - Exposed JSON endpoint for Waffle flag/switch/sample state v2.6.0 ====== - Fixed Django 4.0 compatibility - Added support for custom Sample and Switch models - Added ability to determine if flag is active without persisting new state - Added support for Python 3.10 v2.5.0 ====== - Corrected error in docs - Added setting to support disabling admin pages v2.4.1 ====== - Reverted: Creating missing flags for all attempts to access the missing flag v2.4.0 ====== - Preventing exceptions for template use cases where a request is not available - Creating missing flags for all attempts to access the missing flag - Added Italian translations - Removed universal wheel v2.3.0 ====== - Added support for Django 4.0 v2.2.1 ====== - Resolved deprecation warning when using Jinja2 >= 3 v2.2.0 ====== - Added support for Django 3.2 - Updated documentation for custom flag models - Updated Russian translations v2.1.0 ====== - Added test support for PowerPC - Fixed caching of auto-created missing flags - Fix bug in flag_membership_changed signal handler v2.0.0 ====== - Add support for Django 3.1 - Remove support for Django 1.11, 2.0, 2.1 - Caching auto-created missing flags, switches, and samples v1.0.0 ====== - Removed Python 2.7 compatibility code - Fixed typo in docs example - Documented WAFFLE_TEST_COOKIE v0.20.0 ======= - Dropped support for Python 2.7 - Removed deprecation warnings for ugettext. v0.19.0 ======= - Dropped support for Django 2.0, 2.1, and Python 3.4. - Made tests for Jinja2 optional while waiting for django-jinja to be compatible with Django 3.0. - Add support for Django 3.0 by removing use of deprecated functionality from Django 2.2. v0.18.0 ======= - Updated `MIDDLEWARE` setting name for Django 1.10+ - Improved cache performance for `is_active_for_user` - Corrected log formatting - Added log entries for admin quick link actions - Added permissions for admin actions v0.17.0 ======= - Fixed documentation issues - Added class-based view mixins v0.16.0 ======= - Added support for Django 2.1 and 2.2 - Flushing cache after modifying flags' groups and users - Removed redundant log line - Corrected version in `waffle/__init__.py` - Fixed bug in tests - Using strings as cache keys instead of bytes - Passing effects of test decorator to child classes -- NOTE: This introduced a backwards-incompatible change for the testutils override decorators. See https://github.com/jazzband/django-waffle/pull/331 for details. v0.15.1 ======= - Optionally logging missing flags, samples, and switches - Added --users option to waffle_flag management command - Updated testutils to flush caches - Improved admin site for users and groups - Fixed global cache thread safety issues v0.15.0 ======= - Dropped support for Django < 1.11 - Dropped support for Python 3.3 - Added settings `WAFFLE_CREATE_MISSING_(FLAG|SWITCHES|SAMPLES)` to optionally create missing objects in the database automatically - Allow serializing/de-serializing waffle models by natural key - Added pluggable Flag model v0.14.0 ======= - Added i18n support - Added Russian translations - Add management command to delete waffle data v0.13 ===== - Added support for Django 2.0. - Added support for search the name and notes fields in Django admin. - Fixed small bugs in management commands. - Fixed small documentation issues. - Updated `waffle_flag` management command to accept user groups. - Added setting `WAFFLE_READ_FROM_WRITE_DB` to read from write DB on cache miss. v0.12 ===== - Drop support for Django<1.8 and Python<2.7. - Moved bulk of code from waffle.*_is_active methods to .is_active instance methods. - Centralized caching code behind Class.get() methods. - Significant caching overhaul. - Automatically invalidate cache on waffle upgrade. v0.11.1 ======= - Fix Django 1.9 support. - Fix several Python >=3.4 issues. - Fix output of `waffle_switch --list`. - Fix small documentation issues. - Cache a plain list instead of a ValuesListQuerySet. v0.11 ===== - Support Django 1.8. - Move from jingo-specific to generic Jinja2 template support. - Added tools for integration testing. - Drop Django 1.5 support. - Fix several code and documentation bugs. - Add optional redirect parameter to view decorators. v0.10.2 ======= - Overhaul documentation. - Move CLI commands to waffle_(flag|sample|switch) to be more polite. - Add override_(flag|sample|switch) testing tools. - Changed the default of WAFFLE_SECURE to True. v0.10.1 ======= - Support Python 3. - Support Django 1.7. - Add WAFFLE_CACHE_NAME. - Fix caching for empty lists. v0.10.0 ======= - Replace waffle.get_flags with waffle.{FLAGS,SWITCHES,SAMPLES} in JS. - Update Custom User Models for Django 1.6 support. - Support WaffleJS inline in templates. - Improve test infrastructure and coverage. v0.9.2 ====== - Add get_flags method to waffle.js. - Fix issue with South migrations and custom user models in Django 1.5. - Document command-line access and get more useful information from it. - Support non-naive datetimes when appropriate. - Fix a cache invalidation issue. v0.9.1 ====== - Real Django 1.5 support. - JavaScript obeys WAFFLE_*_DEFAULT settings. v0.9 ==== - Reorganized documentation. - Hash form values for better memcached keys. - Simplified and improved Django template tags. - Renamed JS functions to *_is_active to avoid reserved keywords. v0.8.1 ====== - Fix cache flushing issues. - Fix order of flag_is_active checks. - Add a waffle.urls module. - Add management commands. - Add language support to flags. - Better caching for missing flags/switches/samples. - Re-add 'note' field. - Created a set_flag method to make custom flag cookie triggers easier. v0.8 ==== - Fix issue with repeated flag_is_active calls. - Add created/modified dates to models. - Add WAFFLE_CACHE_PREFIX settings. v0.7.6 ====== - Fix waffle template functions when no request is present. - Added testing mode to flags. - Add WAFFLE_*_DEFAULT for switches and samples. v0.7.5 ====== - Fix issue with stale cache using bulk admin actions. v0.7.4 ====== - Fix waffle.js in Safari. v0.7.2 ====== - Handle 404s correctly. v0.7.1 ====== - I am bad at packaging. v0.7 ==== - Add 'note' field. - Add migrations for Samples. - Clean up Jinja2 functions. v0.6 ==== - Add Samples. v0.5 ==== - Fix waffle.js view with Switches. - Add South migrations. - Cache values to save database queries. v0.4 ==== - Add Switches. v0.3 ==== - Add waffle.js view. v0.2.1 ====== - Add bulk admin actions. v0.2 ==== - Add rollout mode to Flags. django-waffle-4.2.0/CONTRIBUTING.rst000066400000000000000000000051141471570242400166710ustar00rootroot00000000000000.. _about-contributing: .. highlight:: shell ====================== Contributing to Waffle ====================== .. image:: https://jazzband.co/static/img/jazzband.svg :target: https://jazzband.co/ :alt: Jazzband This is a `Jazzband `_ project. By contributing you agree to abide by the `Contributor Code of Conduct `_ and follow the `guidelines `_. Waffle is pretty simple to hack, and has a decent test suite! Here's how to patch Waffle, add tests, run them, and contribute changes. **Please** `open a new issue`_ to discuss a new feature before beginning work on it. Not all suggestions are accepted. The :ref:`Goals ` may help guide which features are likely to be accepted. Set Up ====== Setting up an environment is easy! You'll want ``virtualenv`` and ``pip``, then just create a new virtual environment and install the requirements:: $ mkvirtualenv waffle $ pip install -r requirements.txt Done! Writing Patches =============== Fork_ Waffle and create a new branch off master for your patch. Run the tests often:: $ ./run.sh test Try to keep each branch to a single feature or bugfix. .. note:: To update branches, please **rebase** onto master, do not merge master into your branch. Submitting Patches ================== Open a pull request on GitHub! Before a pull request gets merged, it should be **rebased** onto master and squashed into a minimal set of commits. Each commit should include the necessary code, test, and documentation changes for a single "piece" of functionality. To be mergeable, patches must: - be rebased onto the latest master, - be automatically mergeable, - not break existing tests, - not change existing tests without a *very* good reason, - add tests for new code (bug fixes should include regression tests, new features should have relevant tests), - not introduce any new ruff_ errors (run ``./run.sh lint``), - not introduce any new mypy_ errors (run ``./run.sh typecheck``), - include updated source translations (run ``./run.sh makemessages`` and ``./run.sh compilemessages``), - document any new features, and - have a `good commit message`_. Regressions tests should fail without the rest of the patch and pass with it. .. _open a new issue: https://github.com/jazzband/django-waffle/issues/new .. _Fork: https://github.com/jazzband/django-waffle/fork .. _ruff: https://pypi.python.org/pypi/ruff .. _mypy: https://www.mypy-lang.org/ .. _good commit message: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html django-waffle-4.2.0/LICENSE000066400000000000000000000027601471570242400152410ustar00rootroot00000000000000Copyright (c) 2015 James Socol All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. 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. 3. Neither the name of django-waffle 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 OWNER 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. django-waffle-4.2.0/MANIFEST.in000066400000000000000000000001621471570242400157640ustar00rootroot00000000000000include LICENSE include README.rst include waffle/templates/waffle/waffle.js recursive-include waffle/locale *.mo django-waffle-4.2.0/README.rst000066400000000000000000000014531471570242400157210ustar00rootroot00000000000000====== README ====== Django Waffle is (yet another) feature flipper for Django. You can define the conditions for which a flag should be active, and use it in a number of ways. .. image:: https://jazzband.co/static/img/badge.svg :target: https://jazzband.co/ :alt: Jazzband .. image:: https://github.com/jazzband/django-waffle/workflows/Python%20package/badge.svg?branch=master :target: https://github.com/jazzband/django-waffle/actions :alt: Build Status .. image:: https://badge.fury.io/py/django-waffle.svg :target: https://badge.fury.io/py/django-waffle :alt: PyPI status badge :Code: https://github.com/jazzband/django-waffle :License: BSD; see LICENSE file :Issues: https://github.com/jazzband/django-waffle/issues :Documentation: https://waffle.readthedocs.io/ django-waffle-4.2.0/RELEASING.rst000066400000000000000000000007551471570242400163010ustar00rootroot00000000000000Releasing New Versions ====================== These are the steps necessary to release a new version of Django Waffle. 1. Update the version number in the following files: a. `docs/conf.py` b. `waffle/__init__.py` 2. Update the changelog in `CHANGES`. 3. Merge these changes to the `master` branch. 4. Create a new release on GitHub. This will also create a git tag, and trigger a push to PyPI. 5. Ensure the documentation build passes: https://readthedocs.org/projects/waffle/ django-waffle-4.2.0/docs/000077500000000000000000000000001471570242400151575ustar00rootroot00000000000000django-waffle-4.2.0/docs/Makefile000066400000000000000000000127301471570242400166220ustar00rootroot00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build # 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 " 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 " 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/django-waffle.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-waffle.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/django-waffle" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-waffle" @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." 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." django-waffle-4.2.0/docs/about/000077500000000000000000000000001471570242400162715ustar00rootroot00000000000000django-waffle-4.2.0/docs/about/contributing.rst000066400000000000000000000040511471570242400215320ustar00rootroot00000000000000.. _about-contributing: .. highlight:: shell ====================== Contributing to Waffle ====================== Waffle is pretty simple to hack, and has a decent test suite! Here's how to patch Waffle, add tests, run them, and contribute changes. **Please** `open a new issue`_ to discuss a new feature before beginning work on it. Not all suggestions are accepted. The :ref:`Goals ` may help guide which features are likely to be accepted. Set Up ====== Setting up an environment is easy! You'll want ``virtualenv`` and ``pip``, then just create a new virtual environment and install the requirements:: $ mkvirtualenv waffle $ pip install -r requirements.txt Done! Writing Patches =============== Fork_ Waffle and create a new branch off master for your patch. Run the tests often:: $ ./run.sh test Try to keep each branch to a single feature or bugfix. .. note:: To update branches, please **rebase** onto master, do not merge master into your branch. Submitting Patches ================== Open a pull request on GitHub! Before a pull request gets merged, it should be **rebased** onto master and squashed into a minimal set of commits. Each commit should include the necessary code, test, and documentation changes for a single "piece" of functionality. To be mergeable, patches must: - be rebased onto the latest master, - be automatically mergeable, - not break existing tests, - not change existing tests without a *very* good reason, - add tests for new code (bug fixes should include regression tests, new features should have relevant tests), - not introduce any new ruff_ errors (run ``./run.sh lint``), - document any new features, and - have a `good commit message`_. Regressions tests should fail without the rest of the patch and pass with it. .. _open a new issue: https://github.com/jazzband/django-waffle/issues/new .. _Fork: https://github.com/jazzband/django-waffle/fork .. _ruff: https://pypi.python.org/pypi/ruff .. _good commit message: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html django-waffle-4.2.0/docs/about/goals.rst000066400000000000000000000007751471570242400201410ustar00rootroot00000000000000.. _about-goals: ============== Waffle's goals ============== .. note:: This document is a work in progress. See :ref:`the roadmap `, too. Waffle is designed to - support continuous integration and deployment, - support feature rollout, - with minimum set-up time and learning, - while covering common segments, - and being fast and robust enough for production use. Waffle is **not** designed to - be secure, or be a replacement for permissions, - cover all potential segments. django-waffle-4.2.0/docs/about/roadmap.rst000066400000000000000000000112451471570242400204510ustar00rootroot00000000000000.. _about-roadmap: ======= Roadmap ======= .. note:: This roadmap is subject to change, but represents the rough direction I plan to go. For specific issues, see the current milestones_. Waffle is already a useful library used in many production systems, but it is not done evolving. Present through pre-1.0 ======================= The immediate future is finishing common segment features and bug fixes. 0.10.2–0.11.x ------------- 0.10.2_ was primarily a docs overhaul with a major fix to how caching works. It was combined with 0.11_. It did include test utilities for consumers. 0.11_ updated support, dropping 1.5 and adding 1.8, and overhauled Jinja integration to be compatible with any Jinja2 helper, like jingo or—more future-proof—django-jinja_. 0.11.1 is probably the last release of the 0.11.x_ series. It added support for Django 1.9 without deprecating any other versions. 0.12 ---- 0.12_ includes a couple of significant refactors designed to pay down some of the debt that's accrued in the past few years. It also includes support for Django 1.10 and above. 0.13 ---- 0.13_ drops support for all versions of Django prior to 1.8, including dropping South migrations (and finally being rid of the old issues with them). Along with that, it changes the way settings are configured to be more modern. 0.13 is about closing some long-standing feature gaps, like segmenting by IP and User-Agent. It also includes finally making a decision about auto-create/data-in-settings. Toward 1.0 ========== There are no solid criteria for what makes 1.0 right now, but after 0.13, most outstanding issues will be resolved and Waffle will be in very good shape. There are no plans for a 0.14, so it seems likely that the next step after 0.13 would be some clean-up and finally a 1.0. Beyond 1.0 ========== *tl;dr: Waffle2 may be a complete break from Waffle.* Waffle is one of the first Python libraries I created, you can see that in the amount of code I left in ``__init__.py``. It is also 5 years old, and was created during a different period in my career, and in Django. There are some philosophical issues with how Waffle is designed. Adding new methods of segmenting users requires at least one new column each, and increasing the cyclomatic complexity. Caching is difficult. The requirements are stringent and no longer realistic (they were created before Django 1.5). The distinction between Flags, Samples, and Switches is confusing and triples the API surface area (Flags can easily act as Switches, less easily as Samples). It is not extensible. Some challenges also just accrue over time. Dropping support for Django 1.4, the current Extended Support Release, would significantly simplify a few parts. There is a simplicity to Waffle that I've always appreciated vs, say, Gargoyle_. Not least of which is that Waffle works with the built-in admin (or any other admin you care to use). I don't have to write any code to start using Waffle, other than an ``if`` block. Just add a row and click some checkboxes. Most batteries are included. These are all things that any new version of Waffle must maintain. Still, if I *want* to write code to do some kind of custom segment that isn't common-enough to belong in Waffle, shouldn't I be able to? (And, if all the core segmenters were built as the same kind of extension, we could lower the bar for inclusion.) If I only care about IP address and percentage, it would be great to skip all the other checks that just happen to be higher in the code. I have rough sketches of what this looks like, but there are still some significant sticking points, particularly around shoehorning all of this into the existing Django admin. I believe it's *possible*, just potentially *gross*. (Then again, if it's gross underneath but exposes a pleasant UI, that's not ideal, but it's OK.) The other big sticking point is that this won't be a simple ``ALTER TABLE wafle_flag ADD COLUMN`` upgrade; things will break. I've been thinking what Waffle would be like if I designed it from scratch today with slightly different goals, like extensibility. Beyond 1.0, it's difficult to see continuing to add new features without this kind of overhaul. .. _milestones: https://github.com/jazzband/django-waffle/milestones .. _0.10.2: https://github.com/jazzband/django-waffle/milestones/0.10.2 .. _0.11: https://github.com/jazzband/django-waffle/milestones/0.11 .. _0.11.x: https://github.com/jazzband/django-waffle/milestones/0.11.x .. _0.12: https://github.com/jazzband/django-waffle/milestones/0.12 .. _0.13: https://github.com/jazzband/django-waffle/milestones/0.13 .. _Gargoyle: https://github.com/disqus/gargoyle .. _django-jinja: https://niwinz.github.io/django-jinja/latest/ django-waffle-4.2.0/docs/about/why-waffle.rst000066400000000000000000000030321471570242400210720ustar00rootroot00000000000000.. _about-why-waffle: =========== Why Waffle? =========== `Feature flags`_ are a critical tool for continuously integrating and deploying applications. Waffle is one of `several options`_ for managing feature flags in Django applications. Waffle :ref:`aims to ` - provide a simple, intuitive API everywhere in your application; - cover common use cases with batteries-included; - be simple to install and manage; - be fast and robust enough to use in production; and - minimize dependencies and complexity. Waffle has an `active community`_ and gets `fairly steady updates`_. vs Gargoyle =========== The other major, active feature flag tool for Django is Disqus's Gargoyle_. Both support similar features, though Gargoyle offers more options for building custom segments in exchange for some more complexity and requirements. Waffle in Production ==================== Despite its pre-1.0 version number, Waffle has been used in production for years at places like Mozilla, Yipit and TodaysMeet. - Mozilla (Support, MDN, Addons, etc) - TodaysMeet - Yipit (If you're using Waffle in production and don't mind being included here, let me know or add yourself in a pull request!) .. _Feature flags: http://code.flickr.net/2009/12/02/flipping-out/ .. _several options: https://www.djangopackages.com/grids/g/feature-flip/ .. _active community: https://github.com/jazzband/django-waffle/graphs/contributors .. _fairly steady updates: https://github.com/jazzband/django-waffle/pulse/monthly .. _Gargoyle: https://github.com/disqus/gargoyle django-waffle-4.2.0/docs/conf.py000066400000000000000000000171401471570242400164610ustar00rootroot00000000000000# django-waffle documentation build configuration file, created by # sphinx-quickstart on Wed Aug 1 17:45:05 2012. # # 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 # 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('.')) # -- 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.mathjax'] # 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 = 'django-waffle' copyright = '2012-2018, James Socol' # 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. version = '4.2' # The full version, including alpha/beta/rc tags. release = '4.2.0' # 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 = [] # -- 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 = 'nature' # 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 = {} # 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 = {} # 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 = 'django-waffledoc' # -- 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', 'django-waffle.tex', 'django-waffle Documentation', 'James Socol', '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', 'django-waffle', 'django-waffle Documentation', ['James Socol'], 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', 'django-waffle', 'django-waffle Documentation', 'James Socol', 'django-waffle', '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' django-waffle-4.2.0/docs/index.rst000066400000000000000000000012141471570242400170160ustar00rootroot00000000000000.. _index: ============= Django Waffle ============= Waffle is feature flipper for Django. You can define the conditions for which a flag should be active, and use it in a number of ways. :Version: |release| :Code: https://github.com/jazzband/django-waffle :License: BSD; see LICENSE file :Issues: https://github.com/jazzband/django-waffle/issues Contents: .. toctree:: :titlesonly: about/why-waffle starting/index types/index usage/index testing/index about/contributing about/goals about/roadmap Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` django-waffle-4.2.0/docs/starting/000077500000000000000000000000001471570242400170125ustar00rootroot00000000000000django-waffle-4.2.0/docs/starting/configuring.rst000066400000000000000000000112701471570242400220570ustar00rootroot00000000000000.. _starting-configuring: ================== Configuring Waffle ================== There are a few global settings you can define to adjust Waffle's behavior. ``WAFFLE_COOKIE`` The format for the cookies Waffle sets. Must contain ``%s``. Defaults to ``dwf_%s``. ``WAFFLE_TEST_COOKIE`` The format for the cookies Waffle sets for user testing. Must contain ``%s``. Defaults to ``dwft_%s``. ``WAFFLE_FLAG_DEFAULT`` When a Flag is undefined in the database, Waffle considers it ``False``. Set this to ``True`` to make Waffle consider undefined flags ``True``. Defaults to ``False``. ``WAFFLE_FLAG_MODEL`` The model that will be use to keep track of flags. Defaults to ``waffle.Flag`` which allows user- and group-based flags. Can be swapped for a different Flag model that allows flagging based on other things, such as an organization or a company that a user belongs to. Analogous functionality to Django's extendable User models. Needs to be set at the start of a project, as the Django migrations framework does not support changing swappable models after the initial migration. ``WAFFLE_SWITCH_DEFAULT`` When a Switch is undefined in the database, Waffle considers it ``False``. Set this to ``True`` to make Waffle consider undefined switches ``True``. Defaults to ``False``. ``WAFFLE_SAMPLE_DEFAULT`` When a Sample is undefined in the database, Waffle considers it ``False``. Set this to ``True`` to make Waffle consider undefined samples ``True``. Defaults to ``False``. ``WAFFLE_MAX_AGE`` How long should Waffle cookies last? (Integer, in seconds.) Defaults to ``2529000`` (one month). ``WAFFLE_READ_FROM_WRITE_DB`` When calling ``*_is_active`` methods, Waffle attempts to retrieve a cached version of the object, falling back to the database if necessary. In high- traffic scenarios with multiple databases (e.g. a primary being replicated to a readonly pool) this introduces the risk that a stale version of the object might be cached if one of these methods is called immediately after an update. Set this to ``True`` to ensure Waffle always reads Flags, Switches, and Samples from the DB configured for writes on cache misses. ``WAFFLE_OVERRIDE`` Allow *all* Flags to be controlled via the querystring (to allow e.g. Selenium to control their behavior). Defaults to ``False``. ``WAFFLE_SECURE`` Whether to set the ``secure`` flag on cookies. Defaults to ``True``. ``WAFFLE_CACHE_PREFIX`` Waffle tries to store objects in cache pretty aggressively. If you ever upgrade and change the shape of the objects (for example upgrading from <0.7.5 to >0.7.5) you'll want to set this to something other than ``'waffle:'``. If you're using memcached this should be ASCII only, as that's all it supports. ``WAFFLE_CACHE_NAME`` Which cache to use. Defaults to ``'default'``. ``WAFFLE_CREATE_MISSING_FLAGS`` If Waffle encounters a reference to a flag that is not in the database, should Waffle create the flag? If true new flags are created and set to the value of ``WAFFLE_FLAG_DEFAULT`` Defaults to ``False``. ``WAFFLE_CREATE_MISSING_SWITCHES`` If Waffle encounters a reference to a switch that is not in the database, should Waffle create the switch? If true new switches are created and set to the value of ``WAFFLE_SWITCH_DEFAULT`` Defaults to ``False``. ``WAFFLE_CREATE_MISSING_SAMPLES`` If Waffle encounters a reference to a sample that is not in the database, should Waffle create the sample? If true new samples are created and set to the value of ``WAFFLE_SAMPLE_DEFAULT`` Defaults to ``False``. ``WAFFLE_LOG_MISSING_FLAGS`` If Waffle encounters a reference to a flag that is not in the database, should Waffle log it? The value describes the level of wanted warning, possible values are all levels know by pythons default logging, e.g. ``logging.WARNING``. Defaults to ``None``. ``WAFFLE_LOG_MISSING_SWITCHES`` If Waffle encounters a reference to a switch that is not in the database, should Waffle log it? The value describes the level of wanted warning, possible values are all levels know by pythons default logging, e.g. ``logging.WARNING``. Defaults to ``None``. ``WAFFLE_LOG_MISSING_SAMPLES`` If Waffle encounters a reference to a sample that is not in the database,, should Waffle log it? The value describes the level of wanted warning, possible values are all levels know by pythons default logging, e.g. ``logging.WARNING``. Defaults to ``None``. ``WAFFLE_ENABLE_ADMIN_PAGES`` Enables the default admin pages for Waffle models. This is True by default, but can be disabled to override or customize the pages. django-waffle-4.2.0/docs/starting/index.rst000066400000000000000000000002401471570242400206470ustar00rootroot00000000000000.. _starting-index: =============== Getting Started =============== .. toctree:: :titlesonly: requirements installation upgrading configuring django-waffle-4.2.0/docs/starting/installation.rst000066400000000000000000000052271471570242400222530ustar00rootroot00000000000000.. _starting-installation: ============ Installation ============ After ensuring that the :ref:`requirements ` are met, installing Waffle is a simple process. Getting Waffle ============== Waffle is `hosted on PyPI`_ and can be installed with ``pip`` or ``easy_install``: .. code-block:: shell $ pip install django-waffle $ easy_install django-waffle Waffle is also available `on GitHub`_. In general, ``master`` should be stable, but use caution depending on unreleased versions. .. _hosted on PyPI: http://pypi.python.org/pypi/django-waffle .. _on GitHub: https://github.com/jazzband/django-waffle .. _installation-settings: Settings ======== Add ``waffle`` to the ``INSTALLED_APPS`` setting, and ``waffle.middleware.WaffleMiddleware`` to ``MIDDLEWARE``, e.g.:: INSTALLED_APPS = ( # ... 'waffle', # ... ) MIDDLEWARE = ( # ... 'waffle.middleware.WaffleMiddleware', # ... ) .. _installation-settings-templates: Jinja Templates --------------- .. versionchanged:: 0.19 If you are using Jinja2 templates, the ``django-jinja`` dependency is currently unavailable with django 3.0 and greater; 2.x versions are compatible as well as 1.11. .. versionchanged:: 0.11 If you're using Jinja2 templates, Waffle provides a Jinja2 extension (``waffle.jinja.WaffleExtension``) to :ref:`use Waffle directly from templates `. How you install this depends on which adapter you're using. With django-jinja_, add the extension to the ``extensions`` list:: TEMPLATES = [ { 'BACKEND': 'django_jinja.backend.Jinja2', 'OPTIONS': { 'extensions': [ # ... 'waffle.jinja.WaffleExtension', ], # ... }, # ... }, # ... ] With jingo_, add it to the ``JINJA_CONFIG['extensions']`` list:: JINJA_CONFIG = { 'extensions': [ # ... 'waffle.jinja.WaffleExtension', ], # ... } .. _installation-settings-migrations: Database Schema =============== Waffle includes `Django migrations`_ for creating the correct database schema. If using Django >= 1.7, simply run the ``migrate`` management command after adding Waffle to ``INSTALLED_APPS``: .. code-block:: shell $ django-admin.py migrate If you're using a version of Django without migrations, you can run ``syncdb`` to create the Waffle tables. .. _Django migrations: https://docs.djangoproject.com/en/dev/topics/migrations/ .. _django-jinja: https://pypi.python.org/pypi/django-jinja/ .. _jingo: http://jingo.readthedocs.org/ django-waffle-4.2.0/docs/starting/requirements.rst000066400000000000000000000027551471570242400223000ustar00rootroot00000000000000.. _starting-requirements: ============ Requirements ============ Waffle depends only on Django (except for :ref:`running Waffle's tests `) but does require certain Django features. User Models =========== Waffle requires Django's `auth system`_, in particular it requires both a user model and Django's groups. If you're using a `custom user model`_, this can be accomplished by including Django's `PermissionsMixin`_, e.g.:: from django.contrib.auth import models class MyUser(models.AbstractBaseUser, models.PermissionsMixin): And of ``django.contrib.auth`` must be in ``INSTALLED_APPS``, along with `its requirements`_. .. _auth system: https://docs.djangoproject.com/en/dev/topics/auth/ .. _custom user model: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#specifying-a-custom-user-model .. _PermissionsMixin: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#custom-users-and-permissions .. _its requirements: https://docs.djangoproject.com/en/dev/topics/auth/#installation Templates ========= Waffle provides template tags to check flags directly in templates. Using these requires the ``request`` object in the template context, which can be easily added with the ``request`` `template context processor`_:: TEMPLATE_CONTEXT_PROCESSORS = ( # ... 'django.template.context_processors.request', # ... .. _template context processor: https://docs.djangoproject.com/en/dev/ref/settings/#template-context-processors django-waffle-4.2.0/docs/starting/upgrading.rst000066400000000000000000000007231471570242400215260ustar00rootroot00000000000000.. _starting-upgrading: ========= Upgrading ========= From v0.10.x to v0.11 ===================== Jinja2 Templates ---------------- Waffle no longer supports `jingo's ` automatic helper import, but now ships with a `Jinja2 ` extension that supports multiple Jinja2 template loaders for Django. See the :ref:`installation docs ` for details on how to install this extension. django-waffle-4.2.0/docs/testing/000077500000000000000000000000001471570242400166345ustar00rootroot00000000000000django-waffle-4.2.0/docs/testing/automated.rst000066400000000000000000000043451471570242400213570ustar00rootroot00000000000000.. _testing-automated: ============================= Automated testing with Waffle ============================= Feature flags present a new challenge for writing tests. The test database may not have Flags, Switches, or Samples defined, or they may be non-deterministic. My philosophy, and one I encourage you to adopt, is that tests should cover *both* code paths, with any feature flags on and off. To do this, you'll need to make the code behave deterministically. Here, I'll cover some tips and best practices for testing your app while using feature flags. I'll talk specifically about Flags but this can equally apply to Switches or Samples. Unit tests ========== Waffle provides three context managers (that can also be used as decorators) in ``waffle.testutils`` that make testing easier. - ``override_flag`` - ``override_sample`` - ``override_switch`` All three are used the same way:: with override_flag('flag_name', active=True): # Only 'flag_name' is affected, other flags behave normally. assert waffle.flag_is_active(request, 'flag_name') Or:: @override_sample('sample_name', active=True) def test_with_sample(): # Only 'sample_name' is affected, and will always be True. Other # samples behave normally. assert waffle.sample_is_active('sample_name') All three will restore the relevant flag, sample, or switch to its previous state: they will restore the old values and will delete objects that did not exist. External test suites ==================== Tests that run in a separate process, such as Selenium tests, may not have access to the test database or the ability to mock Waffle values. For tests that make HTTP requests to the system-under-test (e.g. with Selenium_ or PhantomJS_) the ``WAFFLE_OVERRIDE`` :ref:`setting ` makes it possible to control the value of any *Flag* via the querystring. .. highlight:: http For example, for a flag named ``foo``, we can ensure that it is "on" for a request:: GET /testpage?foo=1 HTTP/1.1 or that it is "off":: GET /testpage?foo=0 HTTP/1.1 .. _mock: http://pypi.python.org/pypi/mock/ .. _fudge: http://farmdev.com/projects/fudge/ .. _Selenium: http://www.seleniumhq.org/ .. _PhantomJS: http://phantomjs.org/ django-waffle-4.2.0/docs/testing/index.rst000066400000000000000000000024371471570242400205030ustar00rootroot00000000000000.. _testing-index: =================== Testing with Waffle =================== "Testing" takes on at least two distinct meanings with Waffle: - Testing your application with automated tools - Testing your feature with users For the purposes of this chapter, we'll refer to the former as "automated testing" and the latter as "user testing" for clarity. .. toctree:: :maxdepth: 1 automated user Automated testing ================= Automated testing encompasses things like unit and integration tests, whether they use the Python/Django unittest framework or an external tool like Selenium. Waffle is often non-deterministic, i.e. it introduces true randomness to the system-under-test, which is a nightmare for automated testing. Thus, Waffle includes tools to re-introduce determinism in automated test suites. :ref:`Read more about automated testing `. User testing ============ User testing occurs on both a (relatively) large scale with automated metric collection and on a small, often one-to-one—such as testing sessions with a user and research or turning on a feature within a company or team. Waffle does what it can to support these kinds of tests while still remaining agnostic about metrics platforms. :ref:`Read more about user testing `. django-waffle-4.2.0/docs/testing/user.rst000066400000000000000000000133271471570242400203520ustar00rootroot00000000000000.. _testing-user: ======================== User testing with Waffle ======================== Testing a feature (i.e. not :ref:`testing the code `) with users usually takes one of two forms: small-scale tests with individuals or known group, and large-scale tests with a subset of production users. Waffle provides tools for the former and has some suggestions for the latter. Small-scale tests ================= There are two ways to control a flag for an individual user: - add their account to the flag's list of users, or - use testing mode. Querystring Parameter --------------------- Testing mode makes it possible to enable a flag via a querystring parameter (like ``WAFFLE_OVERRIDE``) but is unique for two reasons: - it can be enabled and disabled on a flag-by-flag basis, and - it only requires the querystring parameter once, then relies on cookies. If the flag we're testing is called ``foo``, then we can enable testing mode, and send users to ``oursite.com/testpage?dwft_foo=1`` (or ``=0``) and the flag will be on (or off) for them for the remainder of their session. .. warning:: Currently, the flag **must** be used by the first page they visit, or the cookie will not get set. See `#80`_ on GitHub. Researchers can send a link with these parameters to anyone and then observe or ask questions. At the end of their session, or when testing mode is deactivated, they will call back to normal behavior. For a small group, like a company or team, it may be worth creating a Django group and adding or removing the group from the flag. HTTP Header ----------- In some cases, such as a backend API, it may be easier for a client to provide an HTTP header instead of a querystring parameter. When a flag, ``foo``, is in testing mode, simply provide the HTTP header ``DWFT-Foo: 1`` (or ``0``) to turn the flag on (or off). This feature can also allow for a downstream service to make the decision of enabling/disabling a flag, and then propagating that decision to other upstream services, allowing for a more complete testing of more complex microservice infrastructures. Order of Precedence ------------------- Since there are multiple controls to explicitly enable and disable flags in testing mode, it's important to understand the order of precedence used to determine when a flag is enabled/disabled when multiple controls are present at once. If any one of these controls is present at all, the subsequent controls will not be checked. 1. Querystring Parameter 2. HTTP Header 3. Cookie Large-scale tests ================= Large scale tests are tests along the lines of "roll this out to 5% of users and observe the relevant metrics." Since "the relevant metrics" is very difficult to define across all sites, here are some thoughts from my experience with these sorts of tests. Client-side metrics ------------------- Google Analytics—and I imagine similar products—has the ability to segment by page or `session variables`_. If you want to A/B test a conversion rate or funnel, or otherwise measure the impact on some client-side metric, using these variables is a solid way to go. For example, in GA, you might do the following to A/B test a landing page: .. code-block:: django ga('set', 'dimension1', 'Landing Page Version {% flag "new_landing_page" %}2{% else %}1{% endif %}'); Similarly you might set session or visitor variables for funnel tests. The exact steps to both set a variable like this and then to create segments and examine the data will depend on your client-side analytics tool. And, of course, this can be combined with other data and further segmented if you need to. Server-side metrics ------------------- I use StatsD_ religiously. Sometimes Waffle is useful for load and capacity testing in which case I want to observe timing data or error rates. Sometimes, it makes sense to create entirely new metrics, and measure them directly, e.g.:: if flag_is_active('image-process-service'): with statsd.timer('imageservice'): try: processed = make_call_to_service(data) except ServiceError: statsd.incr('imageservice.error') else: statsd.incr('imageservice.success') else: with statsd.timer('process-image'): processed = do_inline_processing(data) Other times, existing data—e.g. timers on the whole view—isn't going to move. If you have enough data to be statistically meaningful, you can measure the impact for a given proportion of traffic and derive the time for the new code. If a flag enabling a refactored codepath is set to 20% of users, and average time has improved by 10%, you can calculate that you've improved the speed by 50%! You can use the following to figure out the average for requests using the new code. Let :math:`t_{old}` be the average time with the flag at 0%, :math:`t_{total}` be the average time with the flag at :math:`p * 100%`. Then the average for requests using new code, :math:`t_{new}` is... .. math:: t_{new} = t_{old} - \frac{t_{old} - t_{total}}{p} If you believe my math (you should check it!) then you can measure the average with the flag at 0% to get :math:`t_{old}` (let's say 1.2 seconds), then at :math:`p * 100` % (let's say 20%, so :math:`p = 0.2`) to get :math:`t_{total}` (let's say 1.08 seconds, a 10% improvement) and you have enough to get the average of the new path. .. math:: t_{new} = 1.2 - \frac{1.2 - 1.08}{0.2} = 0.6 Wow, good work! You can use similar methods to derive the impact on other factors. .. _session variables: https://developers.google.com/analytics/devguides/collection/upgrade/reference/gajs-analyticsjs#custom-vars .. _#80: https://github.com/jazzband/django-waffle/issues/80 .. _StatsD: https://github.com/etsy/statsd django-waffle-4.2.0/docs/types/000077500000000000000000000000001471570242400163235ustar00rootroot00000000000000django-waffle-4.2.0/docs/types/flag.rst000066400000000000000000000212441471570242400177710ustar00rootroot00000000000000.. _types-flag: ===== Flags ===== Flags are the most robust, flexible method of rolling out a feature with Waffle. Flags can be used to enable a feature for specific users, groups, users meeting certain criteria (such as being authenticated, or superusers) or a certain percentage of visitors. How Flags Work ============== Flags compare the current request_ to their criteria to decide whether they are active. Consider this simple example:: if flag_is_active(request, 'foo'): pass The :ref:`flag_is_active ` function takes two arguments, the request, and the name of a flag. Assuming this flag (``foo``) is defined in the database, Waffle will make roughly the following decisions: - Is ``WAFFLE_OVERRIDE`` active and if so does this request specify a value for this flag? If so, use that value. - If not, is the flag set to globally on or off (the *Everyone* setting)? If so, use that value. - If not, is the flag in *Testing* mode, and does the request specify a value for this flag? If so, use that value and set a testing cookie. - If not, does the current user meet any of our criteria? If so, the flag is active. - If not, does the user have an existing cookie set for this flag? If so, use that value. - If not, randomly assign a value for this user based on the *Percentage* and set a cookie. Flag Attributes =============== Flags can be administered through the Django `admin site`_ or the :ref:`command line `. They have the following attributes: :Name: The name of the flag. Will be used to identify the flag everywhere. :Everyone: Globally set the Flag, **overriding all other criteria**. Leave as *Unknown* to use other criteria. :Testing: Can the flag be specified via a querystring parameter? :ref:`See below `. :Percent: A percentage of users for whom the flag will be active, if no other criteria applies to them. :Superusers: Is this flag always active for superusers? :Staff: Is this flag always active for staff? :Authenticated: Is this flag always active for authenticated users? :Languages: Is the ``LANGUAGE_CODE`` of the request in this list? (Comma-separated values.) :Groups: A list of group IDs for which this flag will always be active. :Users: A list of user IDs for which this flag will always be active. :Rollout: Activate Rollout mode? :ref:`See below `. :Note: Describe where the flag is used. A Flag will be active if *any* of the criteria are true for the current user or request (i.e. they are combined with ``or``). For example, if a Flag is active for superusers, a specific group, and 12% of visitors, then it will be active if the current user is a superuser *or* if they are in the group *or* if they are in the 12%. .. note:: Users are assigned randomly when using Percentages, so in practice the actual proportion of users for whom the Flag is active will probably differ slightly from the Percentage value. .. _types-flag-custom-model: Custom Flag Models ====================== For many cases, the default Flag model provides all the necessary functionality. It allows flagging individual Users and Groups. If you would like flags to be applied to different things, such as companies a User belongs to, you can use a custom flag model. The functionality uses the same concepts as Django's custom user models, and a lot of this will be immediately recognizable. An application needs to define a ``WAFFLE_FLAG_MODEL`` settings. The default is ``waffle.Flag`` but can be pointed to an arbitrary object. .. note:: It is not possible to change the Flag model and generate working migrations. Ideally, the flag model should be defined at the start of a new project. This is a limitation of the `swappable` Django magic. Please use magic responsibly. The custom Flag model must inherit from `waffle.models.AbstractBaseFlag`. If you want the existing ``User`` and ``Group`` based flagging and would like to add more entities to it, you may extend `waffle.models.AbstractUserFlag`. If you use a custom flag model to apply to models beyond Users and Groups, you must run Django's ``makemigrations`` before running migrations as outlined in the :ref:`installation docs `. If you need to reference the class that is being used as the `Flag` model in your project, use the ``get_waffle_flag_model()`` method. If you reference the Flag a lot, it may be convenient to add ``Flag = get_waffle_flag_model()`` right below your imports and reference the Flag model as if it had been imported directly. Example: .. code-block:: python # settings.py WAFFLE_FLAG_MODEL = 'myapp.Flag' # models.py from waffle.models import AbstractUserFlag, CACHE_EMPTY from waffle.utils import get_setting, keyfmt, get_cache class Flag(AbstractUserFlag): FLAG_COMPANIES_CACHE_KEY = 'FLAG_COMPANIES_CACHE_KEY' FLAG_COMPANIES_CACHE_KEY_DEFAULT = 'flag:%s:companies' companies = models.ManyToManyField( Company, blank=True, help_text=_('Activate this flag for these companies.'), ) def get_flush_keys(self, flush_keys=None): flush_keys = super(Flag, self).get_flush_keys(flush_keys) companies_cache_key = get_setting(Flag.FLAG_COMPANIES_CACHE_KEY, Flag.FLAG_COMPANIES_CACHE_KEY_DEFAULT) flush_keys.append(keyfmt(companies_cache_key, self.name)) return flush_keys def is_active_for_user(self, user): is_active = super(Flag, self).is_active_for_user(user) if is_active: return is_active if getattr(user, 'company_id', None): company_ids = self._get_company_ids() if user.company_id in company_ids: return True def _get_company_ids(self): cache = get_cache() cache_key = keyfmt( get_setting(Flag.FLAG_COMPANIES_CACHE_KEY, Flag.FLAG_COMPANIES_CACHE_KEY_DEFAULT), self.name ) cached = cache.get(cache_key) if cached == CACHE_EMPTY: return set() if cached: return cached company_ids = set(self.companies.all().values_list('pk', flat=True)) if not company_ids: cache.add(cache_key, CACHE_EMPTY) return set() cache.add(cache_key, company_ids) return company_ids # admin.py from waffle.admin import FlagAdmin as WaffleFlagAdmin class FlagAdmin(WaffleFlagAdmin): raw_id_fields = tuple(list(WaffleFlagAdmin.raw_id_fields) + ['companies']) admin.site.register(Flag, FlagAdmin) .. _types-flag-testing: Testing Mode ============ See :ref:`User testing with Waffle `. .. _types-flag-rollout: Rollout Mode ============ When a Flag is activated by chance, Waffle sets a cookie so the flag will not flip back and forth on subsequent visits. This can present a problem for gradually deploying new features: users can get "stuck" with the Flag turned off, even as the percentage increases. *Rollout mode* addresses this by changing the TTL of "off" cookies. When Rollout mode is active, cookies setting the Flag to "off" are session cookies, while those setting the Flag to "on" are still controlled by :ref:`WAFFLE_MAX_AGE `. Effectively, Rollout mode changes the *Percentage* from "percentage of visitors" to "percent chance that the Flag will be activated per visit." .. _request: https://docs.djangoproject.com/en/dev/topics/http/urls/#how-django-processes-a-request .. _admin site: https://docs.djangoproject.com/en/dev/ref/contrib/admin/ .. _types-flag-auto-create-missing: Auto Create Missing =================== When a flag is evaluated in code that is missing in the database the flag returns the :ref:`WAFFLE_FLAG_DEFAULT ` value but does not create a flag in the database. If you'd like waffle to create missing flags in the database whenever it encounters a missing flag you can set :ref:`WAFFLE_CREATE_MISSING_FLAGS ` to ``True``. Missing flags will be created in the database and the value of the ``Everyone`` flag attribute will be set to :ref:`WAFFLE_FLAG_DEFAULT ` in the auto-created database record. .. _types-flag-log-missing: Log Missing =================== Whether or not you enabled :ref:`Auto Create Missing Flags `, it can be practical to be informed that a flag was or is missing. If you'd like waffle to log a warning, error, ... you can set :ref:`WAFFLE_LOG_MISSING_FLAGS ` to any level known by Python default logger. django-waffle-4.2.0/docs/types/index.rst000066400000000000000000000002221471570242400201600ustar00rootroot00000000000000.. _types-index: ===== Types ===== Waffle supports three types of feature flippers: .. toctree:: :maxdepth: 1 flag switch sample django-waffle-4.2.0/docs/types/sample.rst000066400000000000000000000102731471570242400203410ustar00rootroot00000000000000.. _types-sample: ======= Samples ======= Samples are on a given percentage of the time. They do not require a request object and can be used in other contexts, such as management commands and tasks. .. warning:: Sample values are random: if you check a Sample twice, there is no guarantee you will get the same value both times. If you need to rely on the value more than once, you should store it in a variable. :: # YES foo_on = sample_is_active('foo') if foo_on: pass # ...later... if foo_on: pass :: # NO! if sample_is_active('foo'): pass # ...later... if sample_is_active('foo'): # INDEPENDENT of the previous check pass Sample Attributes ================= Samples can be administered through the Django `admin site`_ or the :ref:`command line `. They have the following attributes: :Name: The name of the Sample. :Percent: A number from 0.0 to 100.0 that determines how often the Sample will be active. :Note: Describe where the Sample is used. .. _admin site: https://docs.djangoproject.com/en/dev/ref/contrib/admin/ .. _types-custom-sample-models: Custom Sample Models ====================== For many cases, the default Sample model provides all the necessary functionality. If you would like additional fields not supported by the default Sample model, you can use a custom Sample model. An application needs to define a ``WAFFLE_SAMPLE_MODEL`` settings. The default is ``waffle.Sample`` but can be pointed to an arbitrary object. .. note:: It is not possible to change the Sample model and generate working migrations. Ideally, the Sample model should be defined at the start of a new project. This is a limitation of the `swappable` Django magic. Please use magic responsibly. The custom Sample model must inherit from `waffle.models.AbstractBaseSample`. When using a custom Sample model, you must run Django's ``makemigrations`` before running migrations as outlined in the :ref:`installation docs `. If you need to reference the class that is being used as the `Sample` model in your project, use the ``get_waffle_model('SAMPLE_MODEL')`` method. If you reference the Switch a lot, it may be convenient to add ``Switch = get_waffle_model('SAMPLE_MODEL')`` right below your imports and reference the Sample model as if it had been imported directly. Example: .. code-block:: python # settings.py WAFFLE_SAMPLE_MODEL = 'myapp.Sample' # models.py from waffle.models import AbstractBaseSample, CACHE_EMPTY class Sample(AbstractBaseSample): owner = models.CharField( max_length=100, blank=True, help_text=_('The individual/team who owns this sample.'), ) # admin.py from waffle.admin import SampleAdmin as WaffleSampleAdmin class SampleAdmin(WaffleSampleAdmin): raw_id_fields = tuple(list(WaffleSampleAdmin.raw_id_fields) + ['owner']) admin.site.register(Sample, SampleAdmin) .. _types-sample-auto-create-missing: Auto Create Missing =================== When a sample is evaluated in code that is missing in the database the sample returns the :ref:`WAFFLE_SAMPLE_DEFAULT ` value but does not create a sample in the database. If you'd like waffle to create missing samples in the database whenever it encounters a missing sample you can set :ref:`WAFFLE_CREATE_MISSING_SAMPLES ` to ``True``. If :ref:`WAFFLE_SAMPLE_DEFAULT ` is ``True`` then the ``Percent`` attribute of the sample will be created as 100.0 (so that when the sample is checked it always evaluates to ``True``). Otherwise the value will be set to 0.0 so that the sample always evaluates to ``False``. .. _types-sample-log-missing: Log Missing =================== Whether or not you enabled :ref:`Auto Create Missing Sample `, it can be practical to be informed that a sample was or is missing. If you'd like waffle to log a warning, error, ... you can set :ref:`WAFFLE_LOG_MISSING_SAMPLES ` to any level known by Python default logger. django-waffle-4.2.0/docs/types/switch.rst000066400000000000000000000070151471570242400203610ustar00rootroot00000000000000.. _types-switch: ======== Switches ======== Switches are simple booleans: they are on or off, for everyone, all the time. They do not require a request object and can be used in other contexts, such as management commands and tasks. Switch Attributes ================= Switches can be administered through the Django `admin site`_ or the :ref:`command line `. They have the following attributes: :Name: The name of the Switch. :Active: Is the Switch active or inactive. :Note: Describe where the Switch is used. .. _admin site: https://docs.djangoproject.com/en/dev/ref/contrib/admin/ .. _types-custom-switch-models: Custom Switch Models ====================== For many cases, the default Switch model provides all the necessary functionality. If you would like additional fields not supported by the default Switch model, you can use a custom Switch model. An application needs to define a ``WAFFLE_SWITCH_MODEL`` settings. The default is ``waffle.Switch`` but can be pointed to an arbitrary object. .. note:: It is not possible to change the Switch model and generate working migrations. Ideally, the Switch model should be defined at the start of a new project. This is a limitation of the `swappable` Django magic. Please use magic responsibly. The custom Switch model must inherit from `waffle.models.AbstractBaseSwitch`. When using a custom Switch model, you must run Django's ``makemigrations`` before running migrations as outlined in the :ref:`installation docs `. If you need to reference the class that is being used as the `Switch` model in your project, use the ``get_waffle_model('SWITCH_MODEL')`` method. If you reference the Switch a lot, it may be convenient to add ``Switch = get_waffle_model('SWITCH_MODEL')`` right below your imports and reference the Switch model as if it had been imported directly. Example: .. code-block:: python # settings.py WAFFLE_SWITCH_MODEL = 'myapp.Switch' # models.py from waffle.models import AbstractBaseSwitch, CACHE_EMPTY class Switch(AbstractBaseSwitch): owner = models.CharField( max_length=100, blank=True, help_text=_('The individual/team who owns this switch.'), ) # admin.py from waffle.admin import SwitchAdmin as WaffleSwitchAdmin class SwitchAdmin(WaffleSwitchAdmin): raw_id_fields = tuple(list(WaffleSwitchAdmin.raw_id_fields) + ['owner']) admin.site.register(Switch, SwitchAdmin) .. _types-switch-auto-create-missing: Auto Create Missing =================== When a switch is evaluated in code that is missing in the database the switch returns the :ref:`WAFFLE_SWITCH_DEFAULT ` value but does not create a switch in the database. If you'd like waffle to create missing switches in the database whenever it encounters a missing switch you can set :ref:`WAFFLE_CREATE_MISSING_SWITCHES ` to ``True``. Missing switches will be created in the database and the value of the ``Active`` switch attribute will be set to :ref:`WAFFLE_SWITCH_DEFAULT ` in the auto-created database record. .. _types-switch-log-missing: Log Missing =================== Whether or not you enabled :ref:`Auto Create Missing Switch `, it can be practical to be informed that a switch was or is missing. If you'd like waffle to log a warning, error, ... you can set :ref:`WAFFLE_LOG_MISSING_FLAGS ` to any level known by Python default logger. django-waffle-4.2.0/docs/usage/000077500000000000000000000000001471570242400162635ustar00rootroot00000000000000django-waffle-4.2.0/docs/usage/cli.rst000066400000000000000000000043441471570242400175710ustar00rootroot00000000000000.. _usage-cli: .. highlight:: shell ========================================== Managing Waffle data from the command line ========================================== Aside the Django admin interface, you can use the command line tools to manage all your waffle objects. Flags ===== Use ``manage.py`` to change the values of your flags:: $ ./manage.py waffle_flag name-of-my-flag --everyone --percent=47 Use ``--everyone`` to turn on and ``--deactivate`` to turn off the flag. Set a percentage with ``--percent`` or ``-p``. Set the flag on for superusers (``--superusers``), staff (``--staff``) or authenticated (``--authenticated``) users. Set the rollout mode on with ``--rollout`` or ``-r``. If the flag doesn't exist, add ``--create`` to create it before setting its values:: $ ./manage.py waffle_flag name-of-my-flag --deactivate --create To list all the existing flags, use ``-l``:: $ ./manage.py waffle_flag -l Flags: name-of-my-flag Switches ======== Use ``manage.py`` to change the values of your switches:: $ ./manage.py waffle_switch name-of-my-switch off You can set a switch to ``on`` or ``off``. If that switch doesn't exist, add ``--create`` to create it before setting its value:: $ ./manage.py waffle_switch name-of-my-switch on --create To list all the existing switches, use ``-l``:: $ ./manage.py waffle_switch -l Switches: name-of-my-switch on Samples ======= Use ``manage.py`` to change the values of your samples:: $ ./manage.py waffle_sample name-of-my-sample 100 You can set a sample to any floating value between ``0.0`` and ``100.0``. If that sample doesn't exist, add ``--create`` to create it before setting its value:: $ ./manage.py waffle_sample name-of-my-sample 50.0 --create To list all the existing samples, use ``-l``:: $ ./manage.py waffle_sample -l Samples: name-of-my-sample: 50% Deleting Data ============= Use ``manage.py`` to delete a batch of flags, switches, and/or samples:: $ ./manage.py waffle_delete --switches switch_name_0 switch_name_1 --flags flag_name_0 flag_name_1 --samples sample_name_0 sample_name_1 Pass a list of switch, flag, or sample names to the command as keyword arguments and they will be deleted from the database. django-waffle-4.2.0/docs/usage/decorators.rst000066400000000000000000000026611471570242400211670ustar00rootroot00000000000000.. _usage-decorators: ======================= Decorating entire views ======================= Waffle provides decorators to wrap an entire view in a :ref:`flag ` or :ref:`switch `. (Due to their always-random nature, no decorator is provided for :ref:`samples `.) When the flag or switch is active, the view executes normally. When it is inactive, the view returns a 404. Optionally, you can provide a view or URL name where the decorator can redirect to if you don't want to show a 404 page when the flag or switch is inactive. Flags ===== :: from waffle.decorators import waffle_flag @waffle_flag('flag_name') def myview(request): pass @waffle_flag('flag_name', 'url_name_to_redirect_to') def myotherview(request): pass Switches ======== :: from waffle.decorators import waffle_switch @waffle_switch('switch_name') def myview(request): pass @waffle_switch('switch_name', 'url_name_to_redirect_to') def myotherview(request): pass Inverting Decorators ==================== Both ``waffle_flag`` and ``waffle_switch`` can be reversed (i.e. they will raise a 404 if the flag or switch is *active*, and otherwise execute the view normally) by prepending the name of the flag or switch with an exclamation point: ``!``. :: @waffle_switch('!switch_name') def myview(request): """Only runs if 'switch_name' is OFF.""" django-waffle-4.2.0/docs/usage/index.rst000066400000000000000000000005621471570242400201270ustar00rootroot00000000000000.. _usage-index: ============ Using Waffle ============ Waffle provides a simple API to check the state of :ref:`flags `, :ref:`switches `, and :ref:`samples ` in views and templates, and even on the client in JavaScript. .. toctree:: :titlesonly: views decorators mixins templates javascript json cli django-waffle-4.2.0/docs/usage/javascript.rst000066400000000000000000000032111471570242400211600ustar00rootroot00000000000000.. _usage-javascript: ============== Using WaffleJS ============== Waffle supports using :ref:`flags `, :ref:`switches `, and :ref:`samples ` in JavaScript ("WaffleJS") either via inline script or an external script. .. warning:: Unlike samples when used in Python, samples in WaffleJS **are only calculated once** and so are **consistent**. The WaffleJS ``waffle`` object ============================== WaffleJS exposes a global ``waffle`` object that gives access to flags, switches, and samples. Methods ------- These methods can be used exactly like their Python equivalents: - ``waffle.flag_is_active(flag_name)`` - ``waffle.switch_is_active(switch_name)`` - ``waffle.sample_is_active(sample_name)`` Members ------- WaffleJS also directly exposes dictionaries of each type, where keys are the names and values are ``true`` or ``false``: - ``waffle.FLAGS`` - ``waffle.SWITCHES`` - ``waffle.SAMPLES`` Installing WaffleJS =================== As an external script --------------------- Using the ``wafflejs`` view requires adding Waffle to your URL configuration. For example, in your ``ROOT_URLCONF``:: urlpatterns = patterns('', (r'^', include('waffle.urls')), ) This adds a route called ``wafflejs``, which you can use with the ``url`` template tag: .. code-blocK:: django As an inline script ------------------- To avoid an extra request, you can also use the ``wafflejs`` template tag to include WaffleJS as an inline script: .. code-block:: django {% load waffle_tags %} django-waffle-4.2.0/docs/usage/json.rst000066400000000000000000000034561471570242400177760ustar00rootroot00000000000000.. _usage-json: ===================== Waffle Status as JSON ===================== Although :doc:`WaffleJS` returns the status of all :ref:`flags `, :ref:`switches `, and :ref:`samples `, it does so by exposing a Javascript object, rather than returning the data in a directly consumable format. In cases where a directly consumable format is preferable, Waffle also exposes this data as JSON via the ``waffle_status`` view. Using the view -------------- Using the ``waffle_status`` view requires adding Waffle to your URL configuration. For example, in your ``ROOT_URLCONF``:: urlpatterns = patterns('', (r'^', include('waffle.urls')), ) This adds a route called ``waffle_status``, which will return the current status of each flag, switch, and sample as JSON, with the following structure: .. code-block:: json { "flags": { "flag_active": { "is_active": true, "last_modified": "2020-01-01T12:00:00.000" }, "flag_inactive": { "is_active": false, "last_modified": "2020-01-01T12:00:00.000" } }, "switches": { "switch_active": { "is_active": true, "last_modified": "2020-01-01T12:00:00.000" }, "switch_inactive": { "is_active": false, "last_modified": "2020-01-01T12:00:00.000" } }, "samples": { "sample_active": { "is_active": true, "last_modified": "2020-01-01T12:00:00.000" }, "sample_inactive": { "is_active": false, "last_modified": "2020-01-01T12:00:00.000" } } } django-waffle-4.2.0/docs/usage/mixins.rst000066400000000000000000000015271471570242400203310ustar00rootroot00000000000000.. _usage-mixins: ============================ Mixins for Class Based Views ============================ Waffle provides mixins to add to Class Based Views. When the flag or switch is active, or a sample returns True, the view executes normally. When it is inactive, the view returns a 404. WaffleFlagMixin =============== .. code-block:: python from waffle.mixins import WaffleFlagMixin class MyClass(WaffleFlagMixin, View): waffle_flag = "my_flag" WaffleSwitchMixin ================= .. code-block:: python from waffle.mixins import WaffleSwitchMixin class MyClass(WaffleSwitchMixin, View): waffle_switch= "my_switch" WaffleSampleMixin ================= .. code-block:: python from waffle.mixins import WaffleSampleMixin class MyClass(WaffleSampleMixin, View): waffle_sample= "my_sample" django-waffle-4.2.0/docs/usage/templates.rst000066400000000000000000000036271471570242400210230ustar00rootroot00000000000000.. _usage-templates: .. highlight:: django ========================= Using Waffle in templates ========================= Waffle makes it easy to test :ref:`flags `, :ref:`switches `, and :ref:`samples ` in templates to flip features on the front-end. It includes support for both Django's built-in templates and for Jinja2_. .. warning:: Before using samples in templates, see the warning in the :ref:`Sample chapter `. .. _templates-django: Django Templates ================ Load the ``waffle_tags`` template tags:: {% load waffle_tags %} In Django templates, Waffle provides three new block types, ``flag``, ``switch``, and ``sample``, that function like ``if`` blocks. Each block supports an optional ``else`` to be rendered if the flag, switch, or sample in inactive. Flags ----- :: {% flag "flag_name" %} flag_name is active! {% else %} flag_name is inactive {% endflag %} Switches -------- :: {% switch "switch_name" %} switch_name is active! {% else %} switch_name is inactive {% endswitch %} Samples ------- :: {% sample "sample_name" %} sample_name is active! {% else %} sample_name is inactive {% endsample %} .. _templates-jinja: Jinja Templates =============== When used with Jinja2_, Waffle provides a ``waffle`` object in the Jinja template context that can be used with normal ``if`` statements. Because these are normal ``if`` statements, you can use ``else`` or ``if not`` as normal. Flags ----- :: {% if waffle.flag('flag_name') %} flag_name is active! {% endif %} Switches -------- :: {% if waffle.switch('switch_name') %} switch_name is active! {% endif %} Samples ------- :: {% if waffle.sample('sample_name') %} sample_name is active! {% endif %} .. _Jinja2: http://jinja.pocoo.org/ django-waffle-4.2.0/docs/usage/views.rst000066400000000000000000000017371471570242400201620ustar00rootroot00000000000000.. _usage-views: ===================== Using Waffle in views ===================== Waffle provides simple methods to test :ref:`flags `, :ref:`switches `, or :ref:`samples ` in views (or, for switches and samples, anywhere else you're writing Python). Flags ===== :: waffle.flag_is_active(request, 'flag_name') Returns ``True`` if the flag is active for this request, else ``False``. For example:: import waffle def my_view(request): if waffle.flag_is_active(request, 'flag_name'): """Behavior if flag is active.""" else: """Behavior if flag is inactive.""" Switches ======== :: waffle.switch_is_active('switch_name') Returns ``True`` if the switch is active, else ``False``. Samples ======= :: waffle.sample_is_active('sample_name') Returns ``True`` if the sample is active, else ``False``. .. warning:: See the warning in the :ref:`Sample chapter `. django-waffle-4.2.0/pyproject.toml000066400000000000000000000103301471570242400171400ustar00rootroot00000000000000[build-system] requires = ["setuptools>=61.2"] build-backend = "setuptools.build_meta" [project] name = "django-waffle" dynamic = ["version"] authors = [{name = "James Socol", email = "me@jamessocol.com"}] license = {text = "BSD"} description = "A feature flipper for Django." readme = "README.rst" classifiers = [ "Development Status :: 5 - Production/Stable", "Environment :: Web Environment", "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Framework :: Django", "Framework :: Django :: 3.2", "Framework :: Django :: 4.0", "Framework :: Django :: 4.1", "Framework :: Django :: 4.2", "Framework :: Django :: 5.0", "Framework :: Django :: 5.1", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Topic :: Software Development :: Libraries :: Python Modules", ] requires-python = ">=3.8" dependencies = ["django>=3.2"] [project.urls] Homepage = "http://github.com/django-waffle/django-waffle" [tool.setuptools] zip-safe = false include-package-data = true [tool.setuptools.dynamic] version = {attr = "waffle.__version__"} [tool.setuptools.packages.find] exclude = ["test_app"] # test_settings namespaces = false [tool.setuptools.package-data] waffle = ["py.typed"] [tool.mypy] python_version = "3.8" exclude = "waffle/tests" disallow_incomplete_defs = true disallow_untyped_calls = true disallow_untyped_decorators = true strict_equality = true [[tool.mypy.overrides]] module = ["django.*"] ignore_missing_imports = true [tool.ruff] line-length = 120 target-version = "py38" [tool.ruff.lint] select = [ "AIR", # Airflow "ASYNC", # flake8-async "BLE", # flake8-blind-except "C90", # McCabe cyclomatic complexity "DJ", # flake8-django "DTZ", # flake8-datetimez "E", # pycodestyle errors "F", # Pyflakes "FIX", # flake8-fixme "FLY", # flynt "G", # flake8-logging-format "ICN", # flake8-import-conventions "INP", # flake8-no-pep420 "INT", # flake8-gettext "NPY", # NumPy-specific rules "PD", # pandas-vet "PIE", # flake8-pie "PL", # Pylint "PYI", # flake8-pyi "RSE", # flake8-raise "SLOT", # flake8-slots "T10", # flake8-debugger "T20", # flake8-print "TD", # flake8-todos "TID", # flake8-tidy-imports "UP", # pyupgrade "W", # pycodestyle warnings "YTT", # flake8-2020 # "A", # flake8-builtins # "ANN", # flake8-annotations # "ARG", # flake8-unused-arguments # "B", # flake8-bugbear # "C4", # flake8-comprehensions # "COM", # flake8-commas # "CPY", # flake8-copyright # "D", # pydocstyle # "EM", # flake8-errmsg # "ERA", # eradicate # "EXE", # flake8-executable # "FA", # flake8-future-annotations # "FBT", # flake8-boolean-trap # "I", # isort # "ISC", # flake8-implicit-str-concat # "N", # pep8-naming # "PERF", # Perflint # "PGH", # pygrep-hooks # "PT", # flake8-pytest-style # "PTH", # flake8-use-pathlib # "Q", # flake8-quotes # "RET", # flake8-return # "RUF", # Ruff-specific rules # "S", # flake8-bandit # "SIM", # flake8-simplify # "SLF", # flake8-self # "TCH", # flake8-type-checking # "TRY", # tryceratops ] # Files not checked: # - migrations: most of these are autogenerated and don't need a check # - docs: contains autogenerated code that doesn't need a check exclude = [ "*/migrations/*", "docs", ] ignore = ["F401"] [tool.ruff.lint.mccabe] max-complexity = 23 [tool.ruff.lint.per-file-ignores] "docs/conf.py" = ["INP001"] "test_app/models.py" = ["DJ008"] # FIXME "waffle/models.py" = ["DJ012", "PYI019"] # FIXME [tool.ruff.lint.pylint] allow-magic-value-types = ["float", "int", "str"] max-args = 6 # default is 5 max-branches = 23 # default is 12 max-returns = 13 # default is 6 max-statements = 51 # default is 50 django-waffle-4.2.0/requirements.txt000066400000000000000000000000761471570242400175160ustar00rootroot00000000000000Django django-jinja>=2.4.1,<3 transifex-client mypy ruff tox django-waffle-4.2.0/requirements/000077500000000000000000000000001471570242400167525ustar00rootroot00000000000000django-waffle-4.2.0/requirements/test.txt000066400000000000000000000000111471570242400204620ustar00rootroot00000000000000ruff tox django-waffle-4.2.0/run.sh000077500000000000000000000021421471570242400153710ustar00rootroot00000000000000#!/bin/bash export PYTHONPATH=".:$PYTHONPATH" export DJANGO_SETTINGS_MODULE="test_settings" usage() { echo "USAGE: $0 [command]" echo " test - run the waffle tests" echo " lint - run ruff" echo " typecheck - run mypy" echo " shell - open the Django shell" echo " makemigrations - create a schema migration" exit 1 } CMD="$1" shift case "$CMD" in "test" ) DJANGO_SETTINGS_MODULE=test_settings django-admin test waffle $@ ;; "lint" ) ruff check ;; "typecheck" ) mypy waffle $@ ;; "shell" ) django-admin shell $@ ;; "makemigrations" ) django-admin makemigrations waffle $@ ;; "makemessages" ) export DJANGO_SETTINGS_MODULE= && cd waffle && django-admin makemessages --all && cd - ;; "compilemessages" ) export DJANGO_SETTINGS_MODULE= && cd waffle && django-admin compilemessages && cd - ;; "find_uncommitted_translations" ) git diff --exit-code -G "^(msgid|msgstr)" || (echo "Please run ./run.sh makemessages and commit the updated django.po file." && false) ;; * ) usage ;; esac django-waffle-4.2.0/setup.cfg000066400000000000000000000001421471570242400160450ustar00rootroot00000000000000[flake8] extend-ignore = # break before binary operators W503, # line length E501 django-waffle-4.2.0/test_app/000077500000000000000000000000001471570242400160465ustar00rootroot00000000000000django-waffle-4.2.0/test_app/__init__.py000066400000000000000000000000001471570242400201450ustar00rootroot00000000000000django-waffle-4.2.0/test_app/migrations/000077500000000000000000000000001471570242400202225ustar00rootroot00000000000000django-waffle-4.2.0/test_app/migrations/0001_initial.py000066400000000000000000000100361471570242400226650ustar00rootroot00000000000000# Generated by Django 2.0.4 on 2018-04-26 07:42 from django.conf import settings from django.db import migrations, models import django.db.models.deletion import django.utils.timezone class Migration(migrations.Migration): initial = True dependencies = [ migrations.swappable_dependency(settings.AUTH_USER_MODEL), ] operations = [ migrations.CreateModel( name='Company', fields=[ ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), ('name', models.CharField(max_length=100)), ], ), migrations.CreateModel( name='CompanyAwareFlag', fields=[ ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), ('name', models.CharField(help_text='The human/computer readable name.', max_length=100, unique=True, verbose_name='Name')), ('everyone', models.NullBooleanField(help_text='Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.', verbose_name='Everyone')), ('percent', models.DecimalField(blank=True, decimal_places=1, help_text='A number between 0.0 and 99.9 to indicate a percentage of users for whom this flag will be active.', max_digits=3, null=True, verbose_name='Percent')), ('testing', models.BooleanField(default=False, help_text='Allow this flag to be set for a session for user testing', verbose_name='Testing')), ('superusers', models.BooleanField(default=True, help_text='Flag always active for superusers?', verbose_name='Superusers')), ('staff', models.BooleanField(default=False, help_text='Flag always active for staff?', verbose_name='Staff')), ('authenticated', models.BooleanField(default=False, help_text='Flag always active for authenticated users?', verbose_name='Authenticated')), ('languages', models.TextField(blank=True, default='', help_text='Activate this flag for users with one of these languages (comma-separated list)', verbose_name='Languages')), ('rollout', models.BooleanField(default=False, help_text='Activate roll-out mode?', verbose_name='Rollout')), ('note', models.TextField(blank=True, help_text='Note where this Flag is used.', verbose_name='Note')), ('created', models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Date when this Flag was created.', verbose_name='Created')), ('modified', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Flag was last modified.', verbose_name='Modified')), ('companies', models.ManyToManyField(blank=True, help_text='Activate this flag for these companies.', to='test_app.Company')), ('groups', models.ManyToManyField(blank=True, help_text='Activate this flag for these user groups.', to='auth.Group', verbose_name='Groups')), ('users', models.ManyToManyField(blank=True, help_text='Activate this flag for these users.', to=settings.AUTH_USER_MODEL, verbose_name='Users')), ], options={ 'verbose_name': 'Flag', 'verbose_name_plural': 'Flags', 'abstract': False, }, ), migrations.CreateModel( name='CompanyUser', fields=[ ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), ('password', models.CharField(max_length=128, verbose_name='password')), ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')), ('username', models.CharField(max_length=100)), ('company', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='test_app.Company')), ], options={ 'abstract': False, }, ), ] django-waffle-4.2.0/test_app/migrations/0002_auto_20220717_1934.py000066400000000000000000000055301471570242400236540ustar00rootroot00000000000000# Generated by Django 2.2 on 2022-07-17 19:34 from django.db import migrations, models import django.utils.timezone class Migration(migrations.Migration): dependencies = [ ('test_app', '0001_initial'), ] operations = [ migrations.CreateModel( name='CustomSample', fields=[ ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), ('name', models.CharField(help_text='The human/computer readable name.', max_length=100, unique=True, verbose_name='Name')), ('percent', models.DecimalField(decimal_places=1, help_text='A number between 0.0 and 100.0 to indicate a percentage of the time this sample will be active.', max_digits=4, verbose_name='Percent')), ('note', models.TextField(blank=True, help_text='Note where this Sample is used.', verbose_name='Note')), ('created', models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Date when this Sample was created.', verbose_name='Created')), ('modified', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Sample was last modified.', verbose_name='Modified')), ], options={ 'verbose_name': 'Sample', 'verbose_name_plural': 'Samples', 'abstract': False, }, ), migrations.CreateModel( name='CustomSwitch', fields=[ ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), ('name', models.CharField(help_text='The human/computer readable name.', max_length=100, unique=True, verbose_name='Name')), ('active', models.BooleanField(default=False, help_text='Is this switch active?', verbose_name='Active')), ('note', models.TextField(blank=True, help_text='Note where this Switch is used.', verbose_name='Note')), ('created', models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Date when this Switch was created.', verbose_name='Created')), ('modified', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Switch was last modified.', verbose_name='Modified')), ], options={ 'verbose_name': 'Switch', 'verbose_name_plural': 'Switches', 'abstract': False, }, ), migrations.AlterField( model_name='companyawareflag', name='everyone', field=models.BooleanField(blank=True, help_text='Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.', null=True, verbose_name='Everyone'), ), ] django-waffle-4.2.0/test_app/migrations/__init__.py000066400000000000000000000000001471570242400223210ustar00rootroot00000000000000django-waffle-4.2.0/test_app/models.py000066400000000000000000000045501471570242400177070ustar00rootroot00000000000000from django.contrib.auth.base_user import AbstractBaseUser from django.db import models from django.db.models import CASCADE from django.utils.translation import gettext_lazy as _ from waffle.models import AbstractBaseSample, AbstractBaseSwitch, AbstractUserFlag, CACHE_EMPTY from waffle.utils import get_setting, keyfmt, get_cache cache = get_cache() class Company(models.Model): name = models.CharField( max_length=100, ) class CompanyUser(AbstractBaseUser): company = models.ForeignKey( Company, on_delete=CASCADE ) username = models.CharField( max_length=100, ) class CustomSwitch(AbstractBaseSwitch): """Demonstrates custom switch behavior.""" class CustomSample(AbstractBaseSample): """Demonstrates custom switch behavior.""" class CompanyAwareFlag(AbstractUserFlag): FLAG_COMPANIES_CACHE_KEY = 'FLAG_COMPANIES_CACHE_KEY' FLAG_COMPANIES_CACHE_KEY_DEFAULT = 'flag:%s:companies' companies = models.ManyToManyField( Company, blank=True, help_text=_('Activate this flag for these companies.'), ) def get_flush_keys(self, flush_keys=None): flush_keys = super().get_flush_keys(flush_keys) companies_cache_key = get_setting(CompanyAwareFlag.FLAG_COMPANIES_CACHE_KEY, CompanyAwareFlag.FLAG_COMPANIES_CACHE_KEY_DEFAULT) flush_keys.append(keyfmt(companies_cache_key, self.name)) return flush_keys def is_active_for_user(self, user): is_active = super().is_active_for_user(user) if is_active: return is_active if getattr(user, 'company_id', None): company_ids = self._get_company_ids() if user.company_id in company_ids: return True def _get_company_ids(self): cache_key = keyfmt( get_setting(CompanyAwareFlag.FLAG_COMPANIES_CACHE_KEY, CompanyAwareFlag.FLAG_COMPANIES_CACHE_KEY_DEFAULT), self.name ) cached = cache.get(cache_key) if cached == CACHE_EMPTY: return set() if cached: return cached company_ids = set(self.companies.all().values_list('pk', flat=True)) if not company_ids: cache.add(cache_key, CACHE_EMPTY) return set() cache.add(cache_key, company_ids) return company_ids django-waffle-4.2.0/test_app/templates/000077500000000000000000000000001471570242400200445ustar00rootroot00000000000000django-waffle-4.2.0/test_app/templates/django/000077500000000000000000000000001471570242400213065ustar00rootroot00000000000000django-waffle-4.2.0/test_app/templates/django/django.html000066400000000000000000000007611471570242400234420ustar00rootroot00000000000000{% load waffle_tags %} {% flag flag %} flag on {% else %} flag off {% endflag %} {% switch switch %} switch on {% else %} switch off {% endswitch %} {% sample sample %} sample on {% else %} sample off {% endsample %} {% flag flag_var %} flag_var on {% else %} flag_var off {% endflag %} {% switch switch_var %} switch_var on {% else %} switch_var off {% endswitch %} {% sample sample_var %} sample_var on {% else %} sample_var off {% endsample %} {% wafflejs %} django-waffle-4.2.0/test_app/templates/django/django_email.html000066400000000000000000000002521471570242400246040ustar00rootroot00000000000000{% load waffle_tags %} {% switch switch %} switch on {% else %} switch off {% endswitch %} {% sample sample %} sample on {% else %} sample off {% endsample %} django-waffle-4.2.0/test_app/templates/jinja/000077500000000000000000000000001471570242400211375ustar00rootroot00000000000000django-waffle-4.2.0/test_app/templates/jinja/jinja.html000066400000000000000000000004061471570242400231200ustar00rootroot00000000000000{% if waffle.flag('flag') %} flag on {% else %} flag off {% endif %} {% if waffle.switch('switch') %} switch on {% else %} switch off {% endif %} {% if waffle.sample('sample') %} sample on {% else %} sample off {% endif %} {{ waffle.wafflejs() }} django-waffle-4.2.0/test_app/urls.py000066400000000000000000000040071471570242400174060ustar00rootroot00000000000000from django.urls import include, path from django.contrib import admin from django.http import HttpResponseNotFound, HttpResponseServerError from test_app import views def handler404(r, exception=None): return HttpResponseNotFound() def handler500(r, exception=None): return HttpResponseServerError() admin.autodiscover() urlpatterns = [ path('flag_in_view', views.flag_in_view, name='flag_in_view'), path('flag_in_view_readonly', views.flag_in_view_readonly, name='flag_in_view_readonly'), path('switch-on', views.switched_view), path('switch-off', views.switched_off_view), path('flag-on', views.flagged_view), path('foo_view', views.foo_view, name='foo_view'), path('foo_view_with_args//', views.foo_view_with_args, name='foo_view_with_args'), path('switched_view_with_valid_redirect', views.switched_view_with_valid_redirect), path('switched_view_with_valid_url_name', views.switched_view_with_valid_url_name), path('switched_view_with_args_with_valid_redirect//', views.switched_view_with_args_with_valid_redirect), path('switched_view_with_args_with_valid_url_name//', views.switched_view_with_args_with_valid_url_name), path('switched_view_with_invalid_redirect', views.switched_view_with_invalid_redirect), path('flagged_view_with_valid_redirect', views.flagged_view_with_valid_redirect), path('flagged_view_with_valid_url_name', views.flagged_view_with_valid_url_name), path('flagged_view_with_args_with_valid_redirect//', views.flagged_view_with_args_with_valid_redirect), path('flagged_view_with_args_with_valid_url_name//', views.flagged_view_with_args_with_valid_url_name), path('flagged_view_with_invalid_redirect', views.flagged_view_with_invalid_redirect), path('flag-off', views.flagged_off_view), path('', include('waffle.urls')), path('admin/', admin.site.urls), ] django-waffle-4.2.0/test_app/views.py000066400000000000000000000070271471570242400175630ustar00rootroot00000000000000from django.http import HttpResponse from django.shortcuts import render from django.template.loader import render_to_string from django.views.generic import View from waffle import flag_is_active from waffle.decorators import waffle_flag, waffle_switch from waffle.mixins import WaffleFlagMixin, WaffleSampleMixin, WaffleSwitchMixin def flag_in_view(request): if flag_is_active(request, 'myflag'): return HttpResponse('on') return HttpResponse('off') def flag_in_view_readonly(request): if flag_is_active(request, 'myflag', read_only=True): return HttpResponse('on') return HttpResponse('off') def flag_in_jinja(request): return render(request, 'jinja/jinja.html') def flag_in_django(request): context = { 'flag_var': 'flag_var', 'switch_var': 'switch_var', 'sample_var': 'sample_var', } return render(request, 'django/django.html', context=context) def no_request_context(request): return render_to_string('django/django_email.html', context={}) @waffle_switch('foo') def switched_view(request): return HttpResponse('foo') @waffle_switch('!foo') def switched_off_view(request): return HttpResponse('foo') @waffle_flag('foo') def flagged_view(request): return HttpResponse('foo') @waffle_flag('!foo') def flagged_off_view(request): return HttpResponse('foo') def foo_view(request): return HttpResponse('redirected') def foo_view_with_args(request, some_number): return HttpResponse(f'redirected with {some_number}') @waffle_switch('foo', redirect_to=foo_view) def switched_view_with_valid_redirect(request): return HttpResponse('foo') @waffle_switch('foo', redirect_to='foo_view') def switched_view_with_valid_url_name(request): return HttpResponse('foo') @waffle_switch('foo', redirect_to=foo_view_with_args) def switched_view_with_args_with_valid_redirect(request, some_number): return HttpResponse(f'foo with {some_number}') @waffle_switch('foo', redirect_to='foo_view_with_args') def switched_view_with_args_with_valid_url_name(request, some_number): return HttpResponse(f'foo with {some_number}') @waffle_switch('foo', redirect_to='invalid_view') def switched_view_with_invalid_redirect(request): return HttpResponse('foo') @waffle_flag('foo', redirect_to=foo_view) def flagged_view_with_valid_redirect(request): return HttpResponse('foo') @waffle_flag('foo', redirect_to='foo_view') def flagged_view_with_valid_url_name(request): return HttpResponse('foo') @waffle_flag('foo', redirect_to=foo_view_with_args) def flagged_view_with_args_with_valid_redirect(request, some_number): return HttpResponse(f'foo with {some_number}') @waffle_flag('foo', redirect_to='foo_view_with_args') def flagged_view_with_args_with_valid_url_name(request, some_number): return HttpResponse(f'foo with {some_number}') @waffle_flag('foo', redirect_to='invalid_view') def flagged_view_with_invalid_redirect(request): return HttpResponse('foo') class BaseWaffleView(View): def get(self, request, *args, **kwargs): return HttpResponse('foo') class FlagView(WaffleFlagMixin, BaseWaffleView): waffle_flag = 'foo' class FlagOffView(WaffleFlagMixin, BaseWaffleView): waffle_flag = '!foo' class SampleView(WaffleSampleMixin, BaseWaffleView): waffle_sample = 'foo' class SampleOffView(WaffleSampleMixin, BaseWaffleView): waffle_sample = '!foo' class SwitchView(WaffleSwitchMixin, BaseWaffleView): waffle_switch = 'foo' class SwitchOffView(WaffleSwitchMixin, BaseWaffleView): waffle_switch = '!foo' django-waffle-4.2.0/test_settings.py000066400000000000000000000050121471570242400174760ustar00rootroot00000000000000import os try: import django_jinja JINJA_INSTALLED = True except ImportError: JINJA_INSTALLED = False # Make filepaths relative to settings. ROOT = os.path.dirname(os.path.abspath(__file__)) path = lambda *a: os.path.join(ROOT, *a) # noqa: E731 DEBUG = True TEST_RUNNER = 'django.test.runner.DiscoverRunner' JINJA_CONFIG = {} SITE_ID = 1 USE_I18N = False SECRET_KEY = 'foobar' DATABASES = { 'default': { 'NAME': 'test.db', 'ENGINE': 'django.db.backends.sqlite3', }, # Provide a readonly DB for testing DB replication scenarios. 'readonly': { 'NAME': 'test.readonly.db', 'ENGINE': 'django.db.backends.sqlite3', } } DEFAULT_AUTO_FIELD = 'django.db.models.AutoField' INSTALLED_APPS = ( 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'django.contrib.messages', 'waffle', 'test_app', ) MIDDLEWARE = ( 'django.middleware.common.CommonMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware', 'waffle.middleware.WaffleMiddleware', ) ROOT_URLCONF = 'test_app.urls' _CONTEXT_PROCESSORS = ( 'django.contrib.auth.context_processors.auth', 'django.template.context_processors.request', 'django.contrib.messages.context_processors.messages', ) if JINJA_INSTALLED: TEMPLATES = [ { 'BACKEND': 'django_jinja.backend.Jinja2', 'DIRS': [], 'APP_DIRS': True, 'OPTIONS': { 'match_regex': r'jinja.*', 'match_extension': '', 'newstyle_gettext': True, 'context_processors': _CONTEXT_PROCESSORS, 'undefined': 'jinja2.Undefined', 'extensions': [ 'jinja2.ext.i18n', 'waffle.jinja.WaffleExtension', ], } } ] else: TEMPLATES = [] TEMPLATES.append( { 'BACKEND': 'django.template.backends.django.DjangoTemplates', 'DIRS': [], 'APP_DIRS': True, 'OPTIONS': { 'debug': DEBUG, 'context_processors': _CONTEXT_PROCESSORS, } } ) WAFFLE_FLAG_DEFAULT = False WAFFLE_SWITCH_DEFAULT = False WAFFLE_SAMPLE_DEFAULT = False WAFFLE_READ_FROM_WRITE_DB = False WAFFLE_OVERRIDE = False WAFFLE_ENABLE_ADMIN_PAGES = True WAFFLE_CACHE_PREFIX = 'test:' django-waffle-4.2.0/tox.ini000066400000000000000000000016631471570242400155500ustar00rootroot00000000000000[tox] envlist = py{38,39}-django{32,40,41,42} py{310}-django{32,40,41,42,50,51} py{311}-django{41,42,50,51} py{312}-django{42,50,51} py{313}-django{51} isolated_build = True [gh-actions] python = 3.8: py38 3.9: py39 3.10: py310 3.11: py311 3.12: py312 3.13: py313 [testenv] allowlist_externals = ./run.sh deps = django32: Django>=3.2,<3.3 django40: Django>=4.0,<4.1 django41: Django>=4.1,<4.2 django42: Django>=4.2,<4.3 django50: Django>=5.0,<5.1 django51: Django>=5.1,<5.2 djangomain: https://github.com/django/django/archive/main.tar.gz -r{toxinidir}/requirements.txt commands = ./run.sh test [testenv:i18n] deps = Django>=3.2,<5.2 -r{toxinidir}/requirements.txt commands = ./run.sh makemessages ./run.sh compilemessages ./run.sh find_uncommitted_translations [testenv:typecheck] deps = Django>=3.2,<5.2 -r{toxinidir}/requirements.txt commands = ./run.sh typecheck django-waffle-4.2.0/waffle/000077500000000000000000000000001471570242400154735ustar00rootroot00000000000000django-waffle-4.2.0/waffle/__init__.py000077500000000000000000000042461471570242400176150ustar00rootroot00000000000000from __future__ import annotations from typing import TYPE_CHECKING from django.core.exceptions import ImproperlyConfigured from django.http import HttpRequest from waffle.utils import get_setting from django.apps import apps as django_apps if TYPE_CHECKING: from waffle.models import AbstractBaseFlag, AbstractBaseSample, AbstractBaseSwitch __version__ = '4.2.0' def flag_is_active(request: HttpRequest, flag_name: str, read_only: bool = False) -> bool | None: flag = get_waffle_flag_model().get(flag_name) return flag.is_active(request, read_only=read_only) def switch_is_active(switch_name: str) -> bool: switch = get_waffle_switch_model().get(switch_name) return switch.is_active() def sample_is_active(sample_name: str) -> bool: sample = get_waffle_sample_model().get(sample_name) return sample.is_active() def get_waffle_flag_model() -> type[AbstractBaseFlag]: return get_waffle_model('FLAG_MODEL') def get_waffle_switch_model() -> type[AbstractBaseSwitch]: return get_waffle_model('SWITCH_MODEL') def get_waffle_sample_model() -> type[AbstractBaseSample]: return get_waffle_model('SAMPLE_MODEL') def get_waffle_model(setting_name: str) -> ( type[AbstractBaseFlag | AbstractBaseSwitch | AbstractBaseSample] ): """ Returns the waffle Flag model that is active in this project. """ default_model = { 'FLAG_MODEL': 'waffle.Flag', 'SWITCH_MODEL': 'waffle.Switch', 'SAMPLE_MODEL': 'waffle.Sample', } # Add backwards compatibility by not requiring adding of model setting # for everyone who upgrades. At some point it would be helpful to # require this to be defined explicitly, but no for now, to remove # pain from upgrading. default = default_model[setting_name] flag_model_name = get_setting(setting_name, default) try: return django_apps.get_model(flag_model_name) except ValueError: raise ImproperlyConfigured(f"WAFFLE_{setting_name} must be of the form 'app_label.model_name'") except LookupError: raise ImproperlyConfigured( f"WAFFLE_{setting_name} refers to model '{flag_model_name}' that has not been installed" ) django-waffle-4.2.0/waffle/admin.py000077500000000000000000000112131471570242400171360ustar00rootroot00000000000000from __future__ import annotations from typing import Any from django.contrib import admin from django.contrib.admin.models import LogEntry, CHANGE, DELETION from django.contrib.admin.widgets import ManyToManyRawIdWidget from django.contrib.contenttypes.models import ContentType from django.http import HttpRequest from django.utils.html import escape from django.utils.translation import gettext_lazy as _ from waffle.models import Flag, Sample, Switch from waffle.utils import get_setting class BaseAdmin(admin.ModelAdmin): search_fields = ('name', 'note') def get_actions(self, request: HttpRequest) -> dict[str, Any]: actions = super().get_actions(request) if 'delete_selected' in actions: del actions['delete_selected'] return actions def _add_log_entry(user, model, description, action_flag): LogEntry.objects.create( user=user, content_type=ContentType.objects.get_for_model(type(model)), object_id=model.id, object_repr=model.name + " " + description, action_flag=action_flag ) @admin.action( description=_('Enable selected flags for everyone'), permissions=('change',), ) def enable_for_all(ma, request, qs): # Iterate over all objects to cause cache invalidation. for f in qs.all(): _add_log_entry(request.user, f, "on", CHANGE) f.everyone = True f.save() @admin.action( description=_('Disable selected flags for everyone'), permissions=('change',), ) def disable_for_all(ma, request, qs): # Iterate over all objects to cause cache invalidation. for f in qs.all(): _add_log_entry(request.user, f, "off", CHANGE) f.everyone = False f.save() @admin.action( description=_('Delete selected'), permissions=('delete',), ) def delete_individually(ma, request, qs): # Iterate over all objects to cause cache invalidation. for f in qs.all(): _add_log_entry(request.user, f, "deleted", DELETION) f.delete() class InformativeManyToManyRawIdWidget(ManyToManyRawIdWidget): """Widget for ManyToManyField to Users. Will display the names of the users in a parenthesised list after the input field. This widget works with all models that have a "name" field. """ def label_and_url_for_value(self, values: Any) -> tuple[str, str]: names = [] key = self.rel.get_related_field().name for value in values: try: name = self.rel.model._default_manager \ .using(self.db) \ .get(**{key: value}) names.append(escape(str(name))) except self.rel.model.DoesNotExist: names.append('') return "(" + ", ".join(names) + ")", "" class FlagAdmin(BaseAdmin): actions = [enable_for_all, disable_for_all, delete_individually] list_display = ('name', 'note', 'everyone', 'percent', 'superusers', 'staff', 'authenticated', 'languages') list_filter = ('everyone', 'superusers', 'staff', 'authenticated') raw_id_fields = ('users', ) ordering = ('-id',) def formfield_for_dbfield(self, db_field, **kwargs): if db_field.name == 'users': kwargs.pop('request', None) kwargs['widget'] = \ InformativeManyToManyRawIdWidget(db_field.remote_field, self.admin_site, using=kwargs.get("using")) return db_field.formfield(**kwargs) return super().formfield_for_dbfield(db_field, **kwargs) @admin.action( description=_('Enable selected switches'), permissions=('change',), ) def enable_switches(ma, request, qs): for switch in qs: _add_log_entry(request.user, switch, "on", CHANGE) switch.active = True switch.save() @admin.action( description=_('Disable selected switches'), permissions=('change',), ) def disable_switches(ma, request, qs): for switch in qs: _add_log_entry(request.user, switch, "off", CHANGE) switch.active = False switch.save() class SwitchAdmin(BaseAdmin): actions = [enable_switches, disable_switches, delete_individually] list_display = ('name', 'active', 'note', 'created', 'modified') list_filter = ('active',) ordering = ('-id',) class SampleAdmin(BaseAdmin): actions = [delete_individually] list_display = ('name', 'percent', 'note', 'created', 'modified') ordering = ('-id',) if get_setting('ENABLE_ADMIN_PAGES'): admin.site.register(Flag, FlagAdmin) admin.site.register(Sample, SampleAdmin) admin.site.register(Switch, SwitchAdmin) django-waffle-4.2.0/waffle/apps.py000066400000000000000000000003721471570242400170120ustar00rootroot00000000000000from django.apps import AppConfig class WaffleConfig(AppConfig): name = 'waffle' verbose_name = 'django-waffle' default_auto_field = 'django.db.models.AutoField' def ready(self) -> None: import waffle.signals # noqa: F401 django-waffle-4.2.0/waffle/decorators.py000066400000000000000000000050051471570242400202120ustar00rootroot00000000000000from __future__ import annotations from functools import wraps, WRAPPER_ASSIGNMENTS from typing import Any, Callable from django.http import Http404, HttpRequest, HttpResponse, HttpResponsePermanentRedirect, HttpResponseRedirect from django.shortcuts import redirect from django.urls import reverse, NoReverseMatch from waffle import flag_is_active, switch_is_active def waffle_flag( flag_name: str, redirect_to: Callable | str | None = None, ) -> Callable[[Callable[[HttpRequest], HttpResponse]], Callable[[HttpRequest], HttpResponse]]: def decorator(view: Callable[[HttpRequest], HttpResponse]) -> Callable[[HttpRequest], HttpResponse]: @wraps(view, assigned=WRAPPER_ASSIGNMENTS) def _wrapped_view(request, *args, **kwargs): if flag_name.startswith('!'): active = not flag_is_active(request, flag_name[1:]) else: active = flag_is_active(request, flag_name) if not active: response_to_redirect_to = get_response_to_redirect(redirect_to, *args, **kwargs) if response_to_redirect_to: return response_to_redirect_to else: raise Http404 return view(request, *args, **kwargs) return _wrapped_view return decorator def waffle_switch( switch_name: str, redirect_to: Callable | str | None = None, ) -> Callable[[Callable[[HttpRequest], HttpResponse]], Callable[[HttpRequest], HttpResponse]]: def decorator(view: Callable[[HttpRequest], HttpResponse]) -> Callable[[HttpRequest], HttpResponse]: @wraps(view, assigned=WRAPPER_ASSIGNMENTS) def _wrapped_view(request, *args, **kwargs): if switch_name.startswith('!'): active = not switch_is_active(switch_name[1:]) else: active = switch_is_active(switch_name) if not active: response_to_redirect_to = get_response_to_redirect(redirect_to, *args, **kwargs) if response_to_redirect_to: return response_to_redirect_to else: raise Http404 return view(request, *args, **kwargs) return _wrapped_view return decorator def get_response_to_redirect( view: Callable | str | None, *args: Any, **kwargs: Any, ) -> HttpResponseRedirect | HttpResponsePermanentRedirect | None: try: return redirect(reverse(view, args=args, kwargs=kwargs)) if view else None except NoReverseMatch: return None django-waffle-4.2.0/waffle/defaults.py000066400000000000000000000013441471570242400176560ustar00rootroot00000000000000COOKIE = 'dwf_%s' TEST_COOKIE = 'dwft_%s' SECURE = True MAX_AGE = 2592000 # 1 month in seconds CACHE_PREFIX = 'waffle:' CACHE_NAME = 'default' FLAG_CACHE_KEY = 'flag:%s' FLAG_USERS_CACHE_KEY = 'flag:%s:users' FLAG_GROUPS_CACHE_KEY = 'flag:%s:groups' ALL_FLAGS_CACHE_KEY = 'flags:all' SAMPLE_CACHE_KEY = 'sample:%s' ALL_SAMPLES_CACHE_KEY = 'samples:all' SWITCH_CACHE_KEY = 'switch:%s' ALL_SWITCHES_CACHE_KEY = 'switches:all' FLAG_DEFAULT = False SAMPLE_DEFAULT = False SWITCH_DEFAULT = False READ_FROM_WRITE_DB = False CREATE_MISSING_FLAGS = False CREATE_MISSING_SAMPLES = False CREATE_MISSING_SWITCHES = False LOG_MISSING_FLAGS = None LOG_MISSING_SAMPLES = None LOG_MISSING_SWITCHES = None OVERRIDE = False ENABLE_ADMIN_PAGES = True django-waffle-4.2.0/waffle/jinja.py000066400000000000000000000015251471570242400171430ustar00rootroot00000000000000from jinja2.ext import Extension from waffle import flag_is_active, sample_is_active, switch_is_active from waffle.views import _generate_waffle_js try: from jinja2 import pass_context except ImportError: # NOTE: We can get rid of this when we stop supporting Jinja2 < 3. from jinja2 import contextfunction as pass_context # type: ignore @pass_context def flag_helper(context, flag_name): return flag_is_active(context['request'], flag_name) @pass_context def inline_wafflejs_helper(context): return _generate_waffle_js(context['request']) class WaffleExtension(Extension): def __init__(self, environment): environment.globals['waffle'] = { 'flag': flag_helper, 'switch': switch_is_active, 'sample': sample_is_active, 'wafflejs': inline_wafflejs_helper } django-waffle-4.2.0/waffle/locale/000077500000000000000000000000001471570242400167325ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/en_US/000077500000000000000000000000001471570242400177435ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/en_US/LC_MESSAGES/000077500000000000000000000000001471570242400215305ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/en_US/LC_MESSAGES/django.mo000066400000000000000000000005211471570242400233250ustar00rootroot00000000000000$,89Project-Id-Version: PACKAGE VERSION Report-Msgid-Bugs-To: PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE Last-Translator: FULL NAME Language-Team: LANGUAGE Language: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit django-waffle-4.2.0/waffle/locale/en_US/LC_MESSAGES/django.po000066400000000000000000000074341471570242400233420ustar00rootroot00000000000000# SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER # This file is distributed under the same license as the PACKAGE package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2020-08-18 11:43+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: admin.py:54 msgid "Enable selected flags for everyone" msgstr "" #: admin.py:55 msgid "Disable selected flags for everyone" msgstr "" #: admin.py:56 msgid "Delete selected" msgstr "" #: admin.py:116 msgid "Enable selected switches" msgstr "" #: admin.py:117 msgid "Disable selected switches" msgstr "" #: models.py:128 models.py:407 models.py:470 msgid "The human/computer readable name." msgstr "" #: models.py:129 models.py:408 models.py:471 msgid "Name" msgstr "" #: models.py:135 msgid "" "Flip this flag on (Yes) or off (No) for everyone, overriding all other " "settings. Leave as Unknown to use normally." msgstr "" #: models.py:137 msgid "Everyone" msgstr "" #: models.py:144 msgid "" "A number between 0.0 and 99.9 to indicate a percentage of users for whom " "this flag will be active." msgstr "" #: models.py:146 models.py:478 msgid "Percent" msgstr "" #: models.py:150 msgid "Allow this flag to be set for a session for user testing" msgstr "" #: models.py:151 msgid "Testing" msgstr "" #: models.py:155 msgid "Flag always active for superusers?" msgstr "" #: models.py:156 msgid "Superusers" msgstr "" #: models.py:160 msgid "Flag always active for staff?" msgstr "" #: models.py:161 msgid "Staff" msgstr "" #: models.py:165 msgid "Flag always active for authenticated users?" msgstr "" #: models.py:166 msgid "Authenticated" msgstr "" #: models.py:171 msgid "" "Activate this flag for users with one of these languages (comma-separated " "list)" msgstr "" #: models.py:172 msgid "Languages" msgstr "" #: models.py:176 msgid "Activate roll-out mode?" msgstr "" #: models.py:177 msgid "Rollout" msgstr "" #: models.py:181 msgid "Note where this Flag is used." msgstr "" #: models.py:182 models.py:418 models.py:483 msgid "Note" msgstr "" #: models.py:187 msgid "Date when this Flag was created." msgstr "" #: models.py:188 models.py:424 models.py:489 msgid "Created" msgstr "" #: models.py:192 msgid "Date when this Flag was last modified." msgstr "" #: models.py:193 models.py:429 models.py:494 msgid "Modified" msgstr "" #: models.py:203 models.py:321 models.py:393 msgid "Flag" msgstr "" #: models.py:204 models.py:322 models.py:394 msgid "Flags" msgstr "" #: models.py:309 msgid "Activate this flag for these user groups." msgstr "" #: models.py:310 msgid "Groups" msgstr "" #: models.py:315 msgid "Activate this flag for these users." msgstr "" #: models.py:316 msgid "Users" msgstr "" #: models.py:412 msgid "Is this switch active?" msgstr "" #: models.py:413 msgid "Active" msgstr "" #: models.py:417 msgid "Note where this Switch is used." msgstr "" #: models.py:423 msgid "Date when this Switch was created." msgstr "" #: models.py:428 msgid "Date when this Switch was last modified." msgstr "" #: models.py:438 msgid "Switch" msgstr "" #: models.py:439 msgid "Switches" msgstr "" #: models.py:476 msgid "" "A number between 0.0 and 100.0 to indicate a percentage of the time this " "sample will be active." msgstr "" #: models.py:482 msgid "Note where this Sample is used." msgstr "" #: models.py:488 msgid "Date when this Sample was created." msgstr "" #: models.py:493 msgid "Date when this Sample was last modified." msgstr "" #: models.py:503 msgid "Sample" msgstr "" #: models.py:504 msgid "Samples" msgstr "" django-waffle-4.2.0/waffle/locale/it/000077500000000000000000000000001471570242400173465ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/it/LC_MESSAGES/000077500000000000000000000000001471570242400211335ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/it/LC_MESSAGES/django.mo000066400000000000000000000102411471570242400227300ustar00rootroot000000000000001C,8_9b)#>Ob8  &)"P(s"(#"6Yr{+"rfm     $ / 6 ? !G i "o l n n / % W < FC ( ; * =0 *n =  & #0Tou*z #y')) /;CJR Xcjs!x /(.& '#"%1+-0 ! $ ,)*A number between 0.0 and 100.0 to indicate a percentage of the time this sample will be active.A number between 0.0 and 99.9 to indicate a percentage of users for whom this flag will be active.Activate roll-out mode?Activate this flag for these user groups.Activate this flag for these users.Activate this flag for users with one of these languages (comma-separated list)ActiveAllow this flag to be set for a session for user testingAuthenticatedCreatedDate when this Flag was created.Date when this Flag was last modified.Date when this Sample was created.Date when this Sample was last modified.Date when this Switch was created.Date when this Switch was last modified.Delete selectedDisable selected flags for everyoneDisable selected switchesEnable selected flags for everyoneEnable selected switchesEveryoneFlagFlag always active for authenticated users?Flag always active for staff?Flag always active for superusers?FlagsFlip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.GroupsIs this switch active?LanguagesModifiedNameNoteNote where this Flag is used.Note where this Sample is used.Note where this Switch is used.PercentRolloutSampleSamplesStaffSuperusersSwitchSwitchesTestingThe human/computer readable name.UsersProject-Id-Version: Report-Msgid-Bugs-To: PO-Revision-Date: 2022-03-05 22:05+0100 Language: it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plural-Forms: nplurals=2; plural=(n != 1); Last-Translator: Language-Team: X-Generator: Poedit 2.4.2 Un numero compreso tra 0,0 e 100,0 per indicare una percentuale del tempo in cui questo Sample sarà attivo.Un numero compreso tra 0,0 e 99,9 per indicare una percentuale di utenti per i quali sarà attivo questo flag.Attivare la modalità roll-out?Attiva questo flag per questi gruppi di utenti.Attiva questo flag per questi utenti.Attiva questo flag per gli utenti con una di queste lingue (elenco separato da virgole)AttivoConsenti l'impostazione di questo flag per una sessione di test utenteAutenticatiCreazioneData in cui è stato creato questo Flag.Data in cui questo Flag è stato modificato l'ultima volta.Data in cui è stato creato questo Sample.Data in cui questo Sample è stato modificato l'ultima volta.Data in cui è stato creato questo Switch.Data in cui questo Switch è stato modificato l'ultima volta.Elimina selezionatiDisabilita flags selezionati per tuttiDisabilita switch selezionatiAbilita flags selezionati per tuttiAbilita switch selezionatiTuttiFlagFlag sempre attivo per utenti autenticati?Flag sempre attivo per lo staff?Flag sempre attivo per i superuser?FlagsAttiva (Sì) o disattiva (No) questo flag per tutti, ignorando tutte le altre impostazioni. Lascia non impostato per usarlo normalmente.GruppiQuesto Switch è attivo?LingueModificaNomeNoteNota dove viene utilizzata questo Flag.Nota dove viene utilizzata questo Sample.Nota dove viene utilizzata questo Switch.PercentualeRolloutSampleSamplesStaffSuperusersSwitchSwitchesTestNome leggibile da umani/computer.Utentidjango-waffle-4.2.0/waffle/locale/it/LC_MESSAGES/django.po000066400000000000000000000124351471570242400227420ustar00rootroot00000000000000# SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER # This file is distributed under the same license as the PACKAGE package. # FIRST AUTHOR , YEAR. # msgid "" msgstr "" "Project-Id-Version: \n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2022-03-05 21:37+0100\n" "PO-Revision-Date: 2022-03-05 22:05+0100\n" "Language: it\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=(n != 1);\n" "Last-Translator: \n" "Language-Team: \n" "X-Generator: Poedit 2.4.2\n" #: admin.py:54 msgid "Enable selected flags for everyone" msgstr "Abilita flags selezionati per tutti" #: admin.py:55 msgid "Disable selected flags for everyone" msgstr "Disabilita flags selezionati per tutti" #: admin.py:56 msgid "Delete selected" msgstr "Elimina selezionati" #: admin.py:116 msgid "Enable selected switches" msgstr "Abilita switch selezionati" #: admin.py:117 msgid "Disable selected switches" msgstr "Disabilita switch selezionati" #: models.py:135 models.py:414 models.py:479 msgid "The human/computer readable name." msgstr "Nome leggibile da umani/computer." #: models.py:136 models.py:415 models.py:480 msgid "Name" msgstr "Nome" #: models.py:142 msgid "" "Flip this flag on (Yes) or off (No) for everyone, overriding all other " "settings. Leave as Unknown to use normally." msgstr "" "Attiva (Sì) o disattiva (No) questo flag per tutti, ignorando tutte le altre " "impostazioni. Lascia non impostato per usarlo normalmente." #: models.py:144 msgid "Everyone" msgstr "Tutti" #: models.py:151 msgid "" "A number between 0.0 and 99.9 to indicate a percentage of users for whom " "this flag will be active." msgstr "" "Un numero compreso tra 0,0 e 99,9 per indicare una percentuale di utenti per " "i quali sarà attivo questo flag." #: models.py:153 models.py:487 msgid "Percent" msgstr "Percentuale" #: models.py:157 msgid "Allow this flag to be set for a session for user testing" msgstr "Consenti l'impostazione di questo flag per una sessione di test utente" #: models.py:158 msgid "Testing" msgstr "Test" #: models.py:162 msgid "Flag always active for superusers?" msgstr "Flag sempre attivo per i superuser?" #: models.py:163 msgid "Superusers" msgstr "Superusers" #: models.py:167 msgid "Flag always active for staff?" msgstr "Flag sempre attivo per lo staff?" #: models.py:168 msgid "Staff" msgstr "Staff" #: models.py:172 msgid "Flag always active for authenticated users?" msgstr "Flag sempre attivo per utenti autenticati?" #: models.py:173 msgid "Authenticated" msgstr "Autenticati" #: models.py:178 msgid "" "Activate this flag for users with one of these languages (comma-separated " "list)" msgstr "" "Attiva questo flag per gli utenti con una di queste lingue (elenco separato " "da virgole)" #: models.py:179 msgid "Languages" msgstr "Lingue" #: models.py:183 msgid "Activate roll-out mode?" msgstr "Attivare la modalità roll-out?" #: models.py:184 msgid "Rollout" msgstr "Rollout" #: models.py:188 msgid "Note where this Flag is used." msgstr "Nota dove viene utilizzata questo Flag." #: models.py:189 models.py:425 models.py:492 msgid "Note" msgstr "Note" #: models.py:194 msgid "Date when this Flag was created." msgstr "Data in cui è stato creato questo Flag." #: models.py:195 models.py:431 models.py:498 msgid "Created" msgstr "Creazione" #: models.py:199 msgid "Date when this Flag was last modified." msgstr "Data in cui questo Flag è stato modificato l'ultima volta." #: models.py:200 models.py:436 models.py:503 msgid "Modified" msgstr "Modifica" #: models.py:210 models.py:328 models.py:400 msgid "Flag" msgstr "Flag" #: models.py:211 models.py:329 models.py:401 msgid "Flags" msgstr "Flags" #: models.py:316 msgid "Activate this flag for these user groups." msgstr "Attiva questo flag per questi gruppi di utenti." #: models.py:317 msgid "Groups" msgstr "Gruppi" #: models.py:322 msgid "Activate this flag for these users." msgstr "Attiva questo flag per questi utenti." #: models.py:323 msgid "Users" msgstr "Utenti" #: models.py:419 msgid "Is this switch active?" msgstr "Questo Switch è attivo?" #: models.py:420 msgid "Active" msgstr "Attivo" #: models.py:424 msgid "Note where this Switch is used." msgstr "Nota dove viene utilizzata questo Switch." #: models.py:430 msgid "Date when this Switch was created." msgstr "Data in cui è stato creato questo Switch." #: models.py:435 msgid "Date when this Switch was last modified." msgstr "Data in cui questo Switch è stato modificato l'ultima volta." #: models.py:445 msgid "Switch" msgstr "Switch" #: models.py:446 msgid "Switches" msgstr "Switches" #: models.py:485 msgid "" "A number between 0.0 and 100.0 to indicate a percentage of the time this " "sample will be active." msgstr "" "Un numero compreso tra 0,0 e 100,0 per indicare una percentuale del tempo in " "cui questo Sample sarà attivo." #: models.py:491 msgid "Note where this Sample is used." msgstr "Nota dove viene utilizzata questo Sample." #: models.py:497 msgid "Date when this Sample was created." msgstr "Data in cui è stato creato questo Sample." #: models.py:502 msgid "Date when this Sample was last modified." msgstr "Data in cui questo Sample è stato modificato l'ultima volta." #: models.py:512 msgid "Sample" msgstr "Sample" #: models.py:513 msgid "Samples" msgstr "Samples" django-waffle-4.2.0/waffle/locale/ru/000077500000000000000000000000001471570242400173605ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/ru/LC_MESSAGES/000077500000000000000000000000001471570242400211455ustar00rootroot00000000000000django-waffle-4.2.0/waffle/locale/ru/LC_MESSAGES/django.mo000066400000000000000000000131751471570242400227530ustar00rootroot000000000000001C,8_9b)#>Ob8  &)"P(s"(#"6Yr{+"rfm     $ / 6 ? !G i o 6 3 _$ N oh~? '04Ge.E6"MY!@6 >A4.n?\Q  # BM\cRxRXw  "# 5.d /(.& '#"%1+-0 ! $ ,)*A number between 0.0 and 100.0 to indicate a percentage of the time this sample will be active.A number between 0.0 and 99.9 to indicate a percentage of users for whom this flag will be active.Activate roll-out mode?Activate this flag for these user groups.Activate this flag for these users.Activate this flag for users with one of these languages (comma-separated list)ActiveAllow this flag to be set for a session for user testingAuthenticatedCreatedDate when this Flag was created.Date when this Flag was last modified.Date when this Sample was created.Date when this Sample was last modified.Date when this Switch was created.Date when this Switch was last modified.Delete selectedDisable selected flags for everyoneDisable selected switchesEnable selected flags for everyoneEnable selected switchesEveryoneFlagFlag always active for authenticated users?Flag always active for staff?Flag always active for superusers?FlagsFlip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.GroupsIs this switch active?LanguagesModifiedNameNoteNote where this Flag is used.Note where this Sample is used.Note where this Switch is used.PercentRolloutSampleSamplesStaffSuperusersSwitchSwitchesTestingThe human/computer readable name.UsersProject-Id-Version: PACKAGE VERSION Report-Msgid-Bugs-To: PO-Revision-Date: 2021-01-25 02:20+0000 Last-Translator: Clinton Blackburn , 2021 Language-Team: Russian (https://www.transifex.com/django-waffle/teams/84077/ru/) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language: ru Plural-Forms: nplurals=4; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<12 || n%100>14) ? 1 : n%10==0 || (n%10>=5 && n%10<=9) || (n%100>=11 && n%100<=14)? 2 : 3); Число в интервале от 0.0 до 100.0, указывающее процент проверок, в который эта Проба будет активной.Число в интервале от 0.0 до 99.9, указывающее процент пользователей, для которых этот Флаг будет активен.Активировать режим выкатки?Включить этот Флаг для этих пользовательских групп.Включить этот Флаг для этих пользователей.Включить этот Флаг для пользователей с одним из перечисленных (через запятую) языковВключёнРазрешить включение этого Флага со стороны пользователяАутентифицированные пользователиСозданДата создания этого Флага.Дата последнего изменения этого Флага.Дата создания этой Пробы.Дата последнего изменения этой Пробы.Дата создания этого Тумблера.Дата последнего изменения этого Тумблера.Удалить выбранныеВыключить выбранные Флаги для всехВыключить выбранные ТумблерыВключить выбранные Флаги для всехВключить выбранные ТумблерыПереопределение для всехФлагФлаг всегда активен для аутентифицированных пользователей?Флаг всегда активен для персонала?Флаг всегда активен для суперпользователей?ФлагиВключить (Да) или Выключить (Нет) Флаг для всех, перекрывая все остальные настройки. Оставьте как Неизвестно, чтобы использовать обычный режим работы Флага.ГруппыТумблер включен?ЯзыкиИзменёнИмяПримечаниеПримечание о том, где используется этот Флаг.Примечание о том, где используется эта Проба.Примечание о том, где используется этот Тумблер.ПроцентРежим выкаткиПробаПробыПерсоналСуперпользователиТумблерТумблерыРежим тестированияЧеловеко-/машиночитаемое имяПользователиdjango-waffle-4.2.0/waffle/locale/ru/LC_MESSAGES/django.po000066400000000000000000000155121471570242400227530ustar00rootroot00000000000000# SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER # This file is distributed under the same license as the PACKAGE package. # FIRST AUTHOR , YEAR. # # Translators: # Clinton Blackburn , 2021 # #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2020-08-18 11:43+0100\n" "PO-Revision-Date: 2021-01-25 02:20+0000\n" "Last-Translator: Clinton Blackburn , 2021\n" "Language-Team: Russian (https://www.transifex.com/django-waffle/teams/84077/ru/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Language: ru\n" "Plural-Forms: nplurals=4; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<12 || n%100>14) ? 1 : n%10==0 || (n%10>=5 && n%10<=9) || (n%100>=11 && n%100<=14)? 2 : 3);\n" #: admin.py:54 msgid "Enable selected flags for everyone" msgstr "Включить выбранные Флаги для всех" #: admin.py:55 msgid "Disable selected flags for everyone" msgstr "Выключить выбранные Флаги для всех" #: admin.py:56 msgid "Delete selected" msgstr "Удалить выбранные" #: admin.py:116 msgid "Enable selected switches" msgstr "Включить выбранные Тумблеры" #: admin.py:117 msgid "Disable selected switches" msgstr "Выключить выбранные Тумблеры" #: models.py:128 models.py:407 models.py:470 msgid "The human/computer readable name." msgstr "Человеко-/машиночитаемое имя" #: models.py:129 models.py:408 models.py:471 msgid "Name" msgstr "Имя" #: models.py:135 msgid "" "Flip this flag on (Yes) or off (No) for everyone, overriding all other " "settings. Leave as Unknown to use normally." msgstr "" "Включить (Да) или Выключить (Нет) Флаг для всех, перекрывая все остальные " "настройки. Оставьте как Неизвестно, чтобы использовать обычный режим работы " "Флага." #: models.py:137 msgid "Everyone" msgstr "Переопределение для всех" #: models.py:144 msgid "" "A number between 0.0 and 99.9 to indicate a percentage of users for whom " "this flag will be active." msgstr "" "Число в интервале от 0.0 до 99.9, указывающее процент пользователей, для " "которых этот Флаг будет активен." #: models.py:146 models.py:478 msgid "Percent" msgstr "Процент" #: models.py:150 msgid "Allow this flag to be set for a session for user testing" msgstr "Разрешить включение этого Флага со стороны пользователя" #: models.py:151 msgid "Testing" msgstr "Режим тестирования" #: models.py:155 msgid "Flag always active for superusers?" msgstr "Флаг всегда активен для суперпользователей?" #: models.py:156 msgid "Superusers" msgstr "Суперпользователи" #: models.py:160 msgid "Flag always active for staff?" msgstr "Флаг всегда активен для персонала?" #: models.py:161 msgid "Staff" msgstr "Персонал" #: models.py:165 msgid "Flag always active for authenticated users?" msgstr "Флаг всегда активен для аутентифицированных пользователей?" #: models.py:166 msgid "Authenticated" msgstr "Аутентифицированные пользователи" #: models.py:171 msgid "" "Activate this flag for users with one of these languages (comma-separated " "list)" msgstr "" "Включить этот Флаг для пользователей с одним из перечисленных (через " "запятую) языков" #: models.py:172 msgid "Languages" msgstr "Языки" #: models.py:176 msgid "Activate roll-out mode?" msgstr "Активировать режим выкатки?" #: models.py:177 msgid "Rollout" msgstr "Режим выкатки" #: models.py:181 msgid "Note where this Flag is used." msgstr "Примечание о том, где используется этот Флаг." #: models.py:182 models.py:418 models.py:483 msgid "Note" msgstr "Примечание" #: models.py:187 msgid "Date when this Flag was created." msgstr "Дата создания этого Флага." #: models.py:188 models.py:424 models.py:489 msgid "Created" msgstr "Создан" #: models.py:192 msgid "Date when this Flag was last modified." msgstr "Дата последнего изменения этого Флага." #: models.py:193 models.py:429 models.py:494 msgid "Modified" msgstr "Изменён" #: models.py:203 models.py:321 models.py:393 msgid "Flag" msgstr "Флаг" #: models.py:204 models.py:322 models.py:394 msgid "Flags" msgstr "Флаги" #: models.py:309 msgid "Activate this flag for these user groups." msgstr "Включить этот Флаг для этих пользовательских групп." #: models.py:310 msgid "Groups" msgstr "Группы" #: models.py:315 msgid "Activate this flag for these users." msgstr "Включить этот Флаг для этих пользователей." #: models.py:316 msgid "Users" msgstr "Пользователи" #: models.py:412 msgid "Is this switch active?" msgstr "Тумблер включен?" #: models.py:413 msgid "Active" msgstr "Включён" #: models.py:417 msgid "Note where this Switch is used." msgstr "Примечание о том, где используется этот Тумблер." #: models.py:423 msgid "Date when this Switch was created." msgstr "Дата создания этого Тумблера." #: models.py:428 msgid "Date when this Switch was last modified." msgstr "Дата последнего изменения этого Тумблера." #: models.py:438 msgid "Switch" msgstr "Тумблер" #: models.py:439 msgid "Switches" msgstr "Тумблеры" #: models.py:476 msgid "" "A number between 0.0 and 100.0 to indicate a percentage of the time this " "sample will be active." msgstr "" "Число в интервале от 0.0 до 100.0, указывающее процент проверок, в который " "эта Проба будет активной." #: models.py:482 msgid "Note where this Sample is used." msgstr "Примечание о том, где используется эта Проба." #: models.py:488 msgid "Date when this Sample was created." msgstr "Дата создания этой Пробы." #: models.py:493 msgid "Date when this Sample was last modified." msgstr "Дата последнего изменения этой Пробы." #: models.py:503 msgid "Sample" msgstr "Проба" #: models.py:504 msgid "Samples" msgstr "Пробы" django-waffle-4.2.0/waffle/management/000077500000000000000000000000001471570242400176075ustar00rootroot00000000000000django-waffle-4.2.0/waffle/management/__init__.py000066400000000000000000000000001471570242400217060ustar00rootroot00000000000000django-waffle-4.2.0/waffle/management/commands/000077500000000000000000000000001471570242400214105ustar00rootroot00000000000000django-waffle-4.2.0/waffle/management/commands/__init__.py000066400000000000000000000000001471570242400235070ustar00rootroot00000000000000django-waffle-4.2.0/waffle/management/commands/waffle_delete.py000066400000000000000000000035661471570242400245620ustar00rootroot00000000000000from typing import Any from django.core.management.base import BaseCommand, CommandParser from waffle import ( get_waffle_flag_model, get_waffle_switch_model, get_waffle_sample_model, ) class Command(BaseCommand): def add_arguments(self, parser: CommandParser) -> None: parser.add_argument( '--flags', action='store', dest='flag_names', nargs='*', help='List of flag names to delete.') parser.add_argument( '--samples', action='store', dest='sample_names', nargs='*', help='List of sample names to delete.') parser.add_argument( '--switches', action='store', dest='switch_names', nargs='*', help='List of switch names to delete.') help = 'Delete flags, samples, and switches from database' def handle(self, *args: Any, **options: Any) -> None: flags = options['flag_names'] if flags: flag_queryset = get_waffle_flag_model().objects.filter(name__in=flags) flag_count = flag_queryset.count() flag_queryset.delete() self.stdout.write(f'Deleted {flag_count} Flags') switches = options['switch_names'] if switches: switches_queryset = get_waffle_switch_model().objects.filter( name__in=switches ) switch_count = switches_queryset.count() switches_queryset.delete() self.stdout.write(f'Deleted {switch_count} Switches') samples = options['sample_names'] if samples: sample_queryset = get_waffle_sample_model().objects.filter(name__in=samples) sample_count = sample_queryset.count() sample_queryset.delete() self.stdout.write(f'Deleted {sample_count} Samples') django-waffle-4.2.0/waffle/management/commands/waffle_flag.py000066400000000000000000000163721471570242400242300ustar00rootroot00000000000000from typing import Any from django.contrib.auth import get_user_model from django.contrib.auth.models import Group from django.core.management.base import BaseCommand, CommandError, CommandParser from django.db.models import Q from waffle import get_waffle_flag_model UserModel = get_user_model() class Command(BaseCommand): def add_arguments(self, parser: CommandParser) -> None: parser.add_argument( 'name', nargs='?', help='The name of the flag.') parser.add_argument( '-l', '--list', action='store_true', dest='list_flags', default=False, help='List existing samples.') parser.add_argument( '--everyone', action='store_true', dest='everyone', help='Activate flag for all users.') parser.add_argument( '--deactivate', action='store_false', dest='everyone', help='Deactivate flag for all users.') parser.add_argument( '--percent', '-p', action='store', type=int, dest='percent', help='Roll out the flag for a certain percentage of users. Takes ' 'a number between 0.0 and 100.0') parser.add_argument( '--superusers', action='store_true', dest='superusers', default=False, help='Turn on the flag for Django superusers.') parser.add_argument( '--staff', action='store_true', dest='staff', default=False, help='Turn on the flag for Django staff.') parser.add_argument( '--authenticated', action='store_true', dest='authenticated', default=False, help='Turn on the flag for logged in users.') parser.add_argument( '--group', '-g', action='append', default=list(), help='Turn on the flag for listed group names (use flag more ' 'than once for multiple groups). WARNING: This will remove ' 'any currently associated groups unless --append is used!') parser.add_argument( '--user', '-u', action='append', default=list(), help='Turn on the flag for listed usernames (use flag more ' 'than once for multiple users). WARNING: This will remove ' 'any currently associated users unless --append is used!') parser.add_argument( '--append', action='store_true', dest='append', default=False, help='Append only mode when adding groups.') parser.add_argument( '--rollout', '-r', action='store_true', dest='rollout', default=False, help='Turn on rollout mode.') parser.add_argument( '--testing', '-t', action='store_true', dest='testing', default=False, help='Turn on testing mode, allowing the flag to be specified via ' 'a querystring parameter.') parser.add_argument( '--create', action='store_true', dest='create', default=False, help='If the flag doesn\'t exist, create it.') parser.set_defaults(everyone=None) help = 'Modify a flag.' def handle(self, *args: Any, **options: Any) -> None: if options['list_flags']: self.stdout.write('Flags:') for flag in get_waffle_flag_model().objects.iterator(): self.stdout.write(f'NAME: {flag.name}') self.stdout.write(f'SUPERUSERS: {flag.superusers}') self.stdout.write(f'EVERYONE: {flag.everyone}') self.stdout.write(f'AUTHENTICATED: {flag.authenticated}') self.stdout.write(f'PERCENT: {flag.percent}') self.stdout.write(f'TESTING: {flag.testing}') self.stdout.write(f'ROLLOUT: {flag.rollout}') self.stdout.write(f'STAFF: {flag.staff}') self.stdout.write('GROUPS: {}'.format(list( flag.groups.values_list('name', flat=True))) ) self.stdout.write('USERS: {}'.format(list( flag.users.values_list(UserModel.USERNAME_FIELD, flat=True))) ) self.stdout.write('') return flag_name = options['name'] if not flag_name: raise CommandError('You need to specify a flag name.') if options['create']: flag, created = get_waffle_flag_model().objects.get_or_create(name=flag_name) if created: self.stdout.write(f'Creating flag: {flag_name}') else: try: flag = get_waffle_flag_model().objects.get(name=flag_name) except get_waffle_flag_model().DoesNotExist: raise CommandError('This flag does not exist.') # Loop through all options, setting Flag attributes that # match (ie. don't want to try setting flag.verbosity) for option in options: # Group isn't an attribute on the Flag, but a related Many to Many # field, so we handle it a bit differently by looking up groups and # adding each group to the flag individually if option == 'group': group_hash = {} for group in options['group']: try: group_instance = Group.objects.get(name=group) group_hash[group_instance.name] = group_instance.id except Group.DoesNotExist: raise CommandError(f'Group {group} does not exist') # If 'append' was not passed, we clear related groups if not options['append']: flag.groups.clear() self.stdout.write('Setting group(s): %s' % ( [name for name, _id in group_hash.items()]) ) for group_name, group_id in group_hash.items(): flag.groups.add(group_id) elif option == 'user': user_hash = set() for username in options['user']: try: user_instance = UserModel.objects.get( Q(**{UserModel.USERNAME_FIELD: username}) | Q(**{UserModel.EMAIL_FIELD: username}) ) user_hash.add(user_instance) except UserModel.DoesNotExist: raise CommandError(f'User {username} does not exist') # If 'append' was not passed, we clear related users if not options['append']: flag.users.clear() self.stdout.write(f'Setting user(s): {user_hash}') # for user in user_hash: flag.users.add(*[user.id for user in user_hash]) elif hasattr(flag, option): self.stdout.write(f'Setting {option}: {options[option]}') setattr(flag, option, options[option]) flag.save() django-waffle-4.2.0/waffle/management/commands/waffle_sample.py000066400000000000000000000043761471570242400246010ustar00rootroot00000000000000from typing import Any from django.core.management.base import BaseCommand, CommandError, CommandParser from waffle import get_waffle_sample_model class Command(BaseCommand): def add_arguments(self, parser: CommandParser) -> None: parser.add_argument( 'name', nargs='?', help='The name of the sample.') parser.add_argument( 'percent', nargs='?', type=int, help='The percentage of the time this sample will be active.') parser.add_argument( '-l', '--list', action='store_true', dest='list_samples', default=False, help='List existing samples.') parser.add_argument( '--create', action='store_true', dest='create', default=False, help='If the sample does not exist, create it.') help = 'Change percentage of a sample.' def handle(self, *args: Any, **options: Any) -> None: if options['list_samples']: self.stdout.write('Samples:') for sample in get_waffle_sample_model().objects.iterator(): self.stdout.write(f'{sample.name}: {sample.percent:.1f}%') self.stdout.write('') return sample_name = options['name'] percent = options['percent'] if not (sample_name and percent): raise CommandError( 'You need to specify a sample name and percentage.' ) try: percent = float(percent) if not (0.0 <= percent <= 100.0): raise ValueError except ValueError: raise CommandError('You need to enter a valid percentage value.') if options['create']: sample, created = get_waffle_sample_model().objects.get_or_create( name=sample_name, defaults={'percent': 0}) if created: self.stdout.write(f'Creating sample: {sample_name}') else: try: sample = get_waffle_sample_model().objects.get(name=sample_name) except get_waffle_sample_model().DoesNotExist: raise CommandError('This sample does not exist.') sample.percent = percent sample.save() django-waffle-4.2.0/waffle/management/commands/waffle_switch.py000066400000000000000000000044761471570242400246220ustar00rootroot00000000000000from typing import Any from argparse import ArgumentTypeError from django.core.management.base import BaseCommand, CommandError, CommandParser from waffle import get_waffle_switch_model def on_off_bool(string: str) -> bool: if string not in ['on', 'off']: raise ArgumentTypeError(f"invalid choice: {string!r} (choose from 'on', " "'off')") return string == 'on' class Command(BaseCommand): def add_arguments(self, parser: CommandParser) -> None: parser.add_argument( 'name', nargs='?', help='The name of the switch.') parser.add_argument( 'state', nargs='?', type=on_off_bool, help='The state of the switch: on or off.') parser.add_argument( '-l', '--list', action='store_true', dest='list_switches', default=False, help='List existing switches.') parser.add_argument( '--create', action='store_true', dest='create', default=False, help='If the switch does not exist, create it.') help = 'Activate or deactivate a switch.' def handle(self, *args: Any, **options: Any) -> None: if options['list_switches']: self.stdout.write('Switches:') for switch in get_waffle_switch_model().objects.iterator(): self.stdout.write( '{}: {}'.format(switch.name, 'on' if switch.active else 'off') ) self.stdout.write('') return switch_name = options['name'] state = options['state'] if not (switch_name and state is not None): raise CommandError('You need to specify a switch name and state.') if options["create"]: switch, created = get_waffle_switch_model().objects.get_or_create( name=switch_name ) if created: self.stdout.write(f'Creating switch: {switch_name}') else: try: switch = get_waffle_switch_model().objects.get(name=switch_name) except get_waffle_switch_model().DoesNotExist: raise CommandError('This switch does not exist.') switch.active = state switch.save() django-waffle-4.2.0/waffle/managers.py000066400000000000000000000020251471570242400176410ustar00rootroot00000000000000from typing import TYPE_CHECKING, Any, Generic, TypeVar from django.db import models from waffle.utils import get_setting, get_cache if TYPE_CHECKING: from waffle.models import _BaseModelType, AbstractBaseFlag, AbstractBaseSample, AbstractBaseSwitch # noqa: F401 else: _BaseModelType = TypeVar("_BaseModelType") class BaseManager(models.Manager, Generic[_BaseModelType]): KEY_SETTING = '' def get_by_natural_key(self, name: str) -> _BaseModelType: return self.get(name=name) def create(self, *args: Any, **kwargs: Any) -> _BaseModelType: cache = get_cache() ret = super().create(*args, **kwargs) cache_key = get_setting(self.KEY_SETTING) cache.delete(cache_key) return ret class FlagManager(BaseManager['AbstractBaseFlag']): KEY_SETTING = 'ALL_FLAGS_CACHE_KEY' class SwitchManager(BaseManager['AbstractBaseSwitch']): KEY_SETTING = 'ALL_SWITCHES_CACHE_KEY' class SampleManager(BaseManager['AbstractBaseSample']): KEY_SETTING = 'ALL_SAMPLES_CACHE_KEY' django-waffle-4.2.0/waffle/middleware.py000066400000000000000000000022571471570242400201700ustar00rootroot00000000000000from django.http import HttpRequest, HttpResponse from django.utils.deprecation import MiddlewareMixin from django.utils.encoding import smart_str from waffle.utils import get_setting class WaffleMiddleware(MiddlewareMixin): def process_response(self, request: HttpRequest, response: HttpResponse) -> HttpResponse: secure = get_setting('SECURE') max_age = get_setting('MAX_AGE') if hasattr(request, 'waffles'): for k in request.waffles: name = smart_str(get_setting('COOKIE') % k) active, rollout = request.waffles[k] if rollout and not active: # "Inactive" is a session cookie during rollout mode. age = None else: age = max_age response.set_cookie(name, value=active, max_age=age, secure=secure) if hasattr(request, 'waffle_tests'): for k in request.waffle_tests: name = smart_str(get_setting('TEST_COOKIE') % k) value = request.waffle_tests[k] response.set_cookie(name, value=value) return response django-waffle-4.2.0/waffle/migrations/000077500000000000000000000000001471570242400176475ustar00rootroot00000000000000django-waffle-4.2.0/waffle/migrations/0001_initial.py000066400000000000000000000105701471570242400223150ustar00rootroot00000000000000from django.db import models, migrations import django.utils.timezone from django.conf import settings class Migration(migrations.Migration): dependencies = [ ('auth', '0001_initial'), migrations.swappable_dependency(settings.AUTH_USER_MODEL), ] operations = [ migrations.CreateModel( name='Flag', fields=[ ('id', models.AutoField(verbose_name='ID', serialize=False, auto_created=True, primary_key=True)), ('name', models.CharField(help_text='The human/computer readable name.', unique=True, max_length=100)), ('everyone', models.NullBooleanField(help_text='Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.')), ('percent', models.DecimalField(help_text='A number between 0.0 and 99.9 to indicate a percentage of users for whom this flag will be active.', null=True, max_digits=3, decimal_places=1, blank=True)), ('testing', models.BooleanField(default=False, help_text='Allow this flag to be set for a session for user testing.')), ('superusers', models.BooleanField(default=True, help_text='Flag always active for superusers?')), ('staff', models.BooleanField(default=False, help_text='Flag always active for staff?')), ('authenticated', models.BooleanField(default=False, help_text='Flag always active for authenticate users?')), ('languages', models.TextField(default='', help_text='Activate this flag for users with one of these languages (comma separated list)', blank=True)), ('rollout', models.BooleanField(default=False, help_text='Activate roll-out mode?')), ('note', models.TextField(help_text='Note where this Flag is used.', blank=True)), ('created', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Flag was created.', db_index=True)), ('modified', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Flag was last modified.')), ('groups', models.ManyToManyField(help_text='Activate this flag for these user groups.', to='auth.Group', blank=True)), ('users', models.ManyToManyField(help_text='Activate this flag for these users.', to=settings.AUTH_USER_MODEL, blank=True)), ], options={ }, bases=(models.Model,), ), migrations.CreateModel( name='Sample', fields=[ ('id', models.AutoField(verbose_name='ID', serialize=False, auto_created=True, primary_key=True)), ('name', models.CharField(help_text='The human/computer readable name.', unique=True, max_length=100)), ('percent', models.DecimalField(help_text='A number between 0.0 and 100.0 to indicate a percentage of the time this sample will be active.', max_digits=4, decimal_places=1)), ('note', models.TextField(help_text='Note where this Sample is used.', blank=True)), ('created', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Sample was created.', db_index=True)), ('modified', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Sample was last modified.')), ], options={ }, bases=(models.Model,), ), migrations.CreateModel( name='Switch', fields=[ ('id', models.AutoField(verbose_name='ID', serialize=False, auto_created=True, primary_key=True)), ('name', models.CharField(help_text='The human/computer readable name.', unique=True, max_length=100)), ('active', models.BooleanField(default=False, help_text='Is this flag active?')), ('note', models.TextField(help_text='Note where this Switch is used.', blank=True)), ('created', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Switch was created.', db_index=True)), ('modified', models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Switch was last modified.')), ], options={ 'verbose_name_plural': 'Switches', }, bases=(models.Model,), ), ] django-waffle-4.2.0/waffle/migrations/0002_auto_20161201_0958.py000066400000000000000000000006351471570242400232770ustar00rootroot00000000000000# Generated by Django 1.10.3 on 2016-12-01 09:58 from django.db import migrations, models class Migration(migrations.Migration): dependencies = [ ('waffle', '0001_initial'), ] operations = [ migrations.AlterField( model_name='switch', name='active', field=models.BooleanField(default=False, help_text='Is this switch active?'), ), ] django-waffle-4.2.0/waffle/migrations/0003_update_strings_for_i18n.py000066400000000000000000000151431471570242400254270ustar00rootroot00000000000000# Generated by Django 2.0 on 2018-03-05 22:21 from django.conf import settings from django.db import migrations, models import django.utils.timezone class Migration(migrations.Migration): dependencies = [ ('waffle', '0002_auto_20161201_0958'), ] operations = [ migrations.AlterModelOptions( name='flag', options={'verbose_name': 'Flag', 'verbose_name_plural': 'Flags'}, ), migrations.AlterModelOptions( name='sample', options={'verbose_name': 'Sample', 'verbose_name_plural': 'Samples'}, ), migrations.AlterModelOptions( name='switch', options={'verbose_name': 'Switch', 'verbose_name_plural': 'Switches'}, ), migrations.AlterField( model_name='flag', name='authenticated', field=models.BooleanField(default=False, help_text='Flag always active for authenticated users?', verbose_name='Authenticated'), ), migrations.AlterField( model_name='flag', name='created', field=models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Date when this Flag was created.', verbose_name='Created'), ), migrations.AlterField( model_name='flag', name='everyone', field=models.NullBooleanField(help_text='Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.', verbose_name='Everyone'), ), migrations.AlterField( model_name='flag', name='groups', field=models.ManyToManyField(blank=True, help_text='Activate this flag for these user groups.', to='auth.Group', verbose_name='Groups'), ), migrations.AlterField( model_name='flag', name='languages', field=models.TextField(blank=True, default='', help_text='Activate this flag for users with one of these languages (comma-separated list)', verbose_name='Languages'), ), migrations.AlterField( model_name='flag', name='modified', field=models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Flag was last modified.', verbose_name='Modified'), ), migrations.AlterField( model_name='flag', name='name', field=models.CharField(help_text='The human/computer readable name.', max_length=100, unique=True, verbose_name='Name'), ), migrations.AlterField( model_name='flag', name='note', field=models.TextField(blank=True, help_text='Note where this Flag is used.', verbose_name='Note'), ), migrations.AlterField( model_name='flag', name='percent', field=models.DecimalField(blank=True, decimal_places=1, help_text='A number between 0.0 and 99.9 to indicate a percentage of users for whom this flag will be active.', max_digits=3, null=True, verbose_name='Percent'), ), migrations.AlterField( model_name='flag', name='rollout', field=models.BooleanField(default=False, help_text='Activate roll-out mode?', verbose_name='Rollout'), ), migrations.AlterField( model_name='flag', name='staff', field=models.BooleanField(default=False, help_text='Flag always active for staff?', verbose_name='Staff'), ), migrations.AlterField( model_name='flag', name='superusers', field=models.BooleanField(default=True, help_text='Flag always active for superusers?', verbose_name='Superusers'), ), migrations.AlterField( model_name='flag', name='testing', field=models.BooleanField(default=False, help_text='Allow this flag to be set for a session for user testing', verbose_name='Testing'), ), migrations.AlterField( model_name='flag', name='users', field=models.ManyToManyField(blank=True, help_text='Activate this flag for these users.', to=settings.AUTH_USER_MODEL, verbose_name='Users'), ), migrations.AlterField( model_name='sample', name='created', field=models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Date when this Sample was created.', verbose_name='Created'), ), migrations.AlterField( model_name='sample', name='modified', field=models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Sample was last modified.', verbose_name='Modified'), ), migrations.AlterField( model_name='sample', name='name', field=models.CharField(help_text='The human/computer readable name.', max_length=100, unique=True, verbose_name='Name'), ), migrations.AlterField( model_name='sample', name='note', field=models.TextField(blank=True, help_text='Note where this Sample is used.', verbose_name='Note'), ), migrations.AlterField( model_name='sample', name='percent', field=models.DecimalField(decimal_places=1, help_text='A number between 0.0 and 100.0 to indicate a percentage of the time this sample will be active.', max_digits=4, verbose_name='Percent'), ), migrations.AlterField( model_name='switch', name='active', field=models.BooleanField(default=False, help_text='Is this switch active?', verbose_name='Active'), ), migrations.AlterField( model_name='switch', name='created', field=models.DateTimeField(db_index=True, default=django.utils.timezone.now, help_text='Date when this Switch was created.', verbose_name='Created'), ), migrations.AlterField( model_name='switch', name='modified', field=models.DateTimeField(default=django.utils.timezone.now, help_text='Date when this Switch was last modified.', verbose_name='Modified'), ), migrations.AlterField( model_name='switch', name='name', field=models.CharField(help_text='The human/computer readable name.', max_length=100, unique=True, verbose_name='Name'), ), migrations.AlterField( model_name='switch', name='note', field=models.TextField(blank=True, help_text='Note where this Switch is used.', verbose_name='Note'), ), ] django-waffle-4.2.0/waffle/migrations/0004_update_everyone_nullbooleanfield.py000066400000000000000000000010521471570242400274560ustar00rootroot00000000000000# Generated by Django 3.0.9 on 2020-08-18 04:55 from django.db import migrations, models class Migration(migrations.Migration): dependencies = [ ('waffle', '0003_update_strings_for_i18n'), ] operations = [ migrations.AlterField( model_name='flag', name='everyone', field=models.BooleanField(blank=True, help_text='Flip this flag on (Yes) or off (No) for everyone, overriding all other settings. Leave as Unknown to use normally.', null=True, verbose_name='Everyone'), ), ] django-waffle-4.2.0/waffle/migrations/__init__.py000066400000000000000000000000001471570242400217460ustar00rootroot00000000000000django-waffle-4.2.0/waffle/mixins.py000066400000000000000000000034341471570242400173600ustar00rootroot00000000000000from __future__ import annotations from functools import partial from django.http import Http404 from waffle import switch_is_active, flag_is_active, sample_is_active class BaseWaffleMixin: def validate_waffle(self, waffle, func): if waffle.startswith('!'): active = not func(waffle[1:]) else: active = func(waffle) return active def invalid_waffle(self): raise Http404('Inactive waffle') class WaffleFlagMixin(BaseWaffleMixin): """ Checks that as flag is active, or 404. Operates like the FBV decorator waffle_flag """ waffle_flag: str | None = None def dispatch(self, request, *args, **kwargs): func = partial(flag_is_active, request) active = self.validate_waffle(self.waffle_flag, func) if not active: return self.invalid_waffle() return super().dispatch(request, *args, **kwargs) class WaffleSampleMixin(BaseWaffleMixin): """ Checks that as switch is active, or 404. Operates like the FBV decorator waffle_sample. """ waffle_sample: str | None = None def dispatch(self, request, *args, **kwargs): active = self.validate_waffle(self.waffle_sample, sample_is_active) if not active: return self.invalid_waffle() return super().dispatch(request, *args, **kwargs) class WaffleSwitchMixin(BaseWaffleMixin): """ Checks that as switch is active, or 404. Operates like the FBV decorator waffle_switch. """ waffle_switch: str | None = None def dispatch(self, request, *args, **kwargs): active = self.validate_waffle(self.waffle_switch, switch_is_active) if not active: return self.invalid_waffle() return super().dispatch(request, *args, **kwargs) django-waffle-4.2.0/waffle/models.py000066400000000000000000000425771471570242400173470ustar00rootroot00000000000000from __future__ import annotations import logging import random from decimal import Decimal from typing import Any, TypeVar from django.conf import settings from django.contrib.auth.models import AbstractBaseUser, Group from django.db import models, router, transaction from django.http import HttpRequest from django.utils import timezone from django.utils.translation import gettext_lazy as _ from waffle import ( get_waffle_sample_model, get_waffle_switch_model, get_waffle_flag_model, managers, ) from waffle.utils import get_setting, keyfmt, get_cache logger = logging.getLogger('waffle') CACHE_EMPTY = '-' _BaseModelType = TypeVar("_BaseModelType", bound="BaseModel") class BaseModel(models.Model): SINGLE_CACHE_KEY = '' ALL_CACHE_KEY = '' class Meta: abstract = True def __str__(self) -> str: return self.name def natural_key(self) -> tuple[str]: return (self.name,) @classmethod def _cache_key(cls, name: str) -> str: return keyfmt(get_setting(cls.SINGLE_CACHE_KEY), name) @classmethod def get(cls: type[_BaseModelType], name: str) -> _BaseModelType: cache = get_cache() cache_key = cls._cache_key(name) cached = cache.get(cache_key) if cached == CACHE_EMPTY: return cls(name=name) if cached: return cached try: obj = cls.get_from_db(name) except cls.DoesNotExist: cache.add(cache_key, CACHE_EMPTY) return cls(name=name) cache.add(cache_key, obj) return obj @classmethod def get_from_db(cls: type[_BaseModelType], name: str) -> _BaseModelType: objects = cls.objects if get_setting('READ_FROM_WRITE_DB'): objects = objects.using(router.db_for_write(cls)) return objects.get(name=name) @classmethod def get_all(cls: type[_BaseModelType]) -> list[_BaseModelType]: cache = get_cache() cache_key = get_setting(cls.ALL_CACHE_KEY) cached = cache.get(cache_key) if cached == CACHE_EMPTY: return [] if cached: return cached objs = cls.get_all_from_db() if not objs: cache.add(cache_key, CACHE_EMPTY) return [] cache.add(cache_key, objs) return objs @classmethod def get_all_from_db(cls: type[_BaseModelType]) -> list[_BaseModelType]: objects = cls.objects if get_setting('READ_FROM_WRITE_DB'): objects = objects.using(router.db_for_write(cls)) return list(objects.all()) def flush(self) -> None: cache = get_cache() keys = [ self._cache_key(self.name), get_setting(self.ALL_CACHE_KEY), ] cache.delete_many(keys) def save(self, *args: Any, **kwargs: Any) -> None: self.modified = timezone.now() ret = super().save(*args, **kwargs) if hasattr(transaction, 'on_commit'): transaction.on_commit(self.flush) else: self.flush() return ret def delete(self, *args: Any, **kwargs: Any) -> tuple[int, dict[str, int]]: ret = super().delete(*args, **kwargs) if hasattr(transaction, 'on_commit'): transaction.on_commit(self.flush) else: self.flush() return ret def set_flag(request: HttpRequest, flag_name: str, active: bool | None = True, session_only: bool = False) -> None: """Set a flag value on a request object.""" if not hasattr(request, 'waffles'): request.waffles = {} request.waffles[flag_name] = [active, session_only] class AbstractBaseFlag(BaseModel): """A feature flag. Flags are active (or not) on a per-request basis. """ name = models.CharField( max_length=100, unique=True, help_text=_('The human/computer readable name.'), verbose_name=_('Name'), ) everyone = models.BooleanField( blank=True, null=True, help_text=_( 'Flip this flag on (Yes) or off (No) for everyone, overriding all ' 'other settings. Leave as Unknown to use normally.'), verbose_name=_('Everyone'), ) percent = models.DecimalField( max_digits=3, decimal_places=1, null=True, blank=True, help_text=_('A number between 0.0 and 99.9 to indicate a percentage of ' 'users for whom this flag will be active.'), verbose_name=_('Percent'), ) testing = models.BooleanField( default=False, help_text=_('Allow this flag to be set for a session for user testing'), verbose_name=_('Testing'), ) superusers = models.BooleanField( default=True, help_text=_('Flag always active for superusers?'), verbose_name=_('Superusers'), ) staff = models.BooleanField( default=False, help_text=_('Flag always active for staff?'), verbose_name=_('Staff'), ) authenticated = models.BooleanField( default=False, help_text=_('Flag always active for authenticated users?'), verbose_name=_('Authenticated'), ) languages = models.TextField( blank=True, default='', help_text=_('Activate this flag for users with one of these languages (comma-separated list)'), verbose_name=_('Languages'), ) rollout = models.BooleanField( default=False, help_text=_('Activate roll-out mode?'), verbose_name=_('Rollout'), ) note = models.TextField( blank=True, help_text=_('Note where this Flag is used.'), verbose_name=_('Note'), ) created = models.DateTimeField( default=timezone.now, db_index=True, help_text=_('Date when this Flag was created.'), verbose_name=_('Created'), ) modified = models.DateTimeField( default=timezone.now, help_text=_('Date when this Flag was last modified.'), verbose_name=_('Modified'), ) objects = managers.FlagManager() SINGLE_CACHE_KEY = 'FLAG_CACHE_KEY' ALL_CACHE_KEY = 'ALL_FLAGS_CACHE_KEY' class Meta: abstract = True verbose_name = _('Flag') verbose_name_plural = _('Flags') def flush(self) -> None: cache = get_cache() keys = self.get_flush_keys() cache.delete_many(keys) def get_flush_keys(self, flush_keys: list[str] | None = None) -> list[str]: flush_keys = flush_keys or [] flush_keys.extend([ self._cache_key(self.name), get_setting('ALL_FLAGS_CACHE_KEY'), ]) return flush_keys def is_active_for_user(self, user: AbstractBaseUser) -> bool | None: if self.everyone: return True if self.authenticated and user.is_authenticated: return True if self.staff and getattr(user, 'is_staff', False): return True if self.superusers and getattr(user, 'is_superuser', False): return True return None def _is_active_for_user(self, request: HttpRequest) -> bool | None: user = getattr(request, "user", None) if user: return self.is_active_for_user(user) return False def _is_active_for_language(self, request: HttpRequest) -> bool | None: if self.languages: languages = [ln.strip() for ln in self.languages.split(',')] if (hasattr(request, 'LANGUAGE_CODE') and request.LANGUAGE_CODE in languages): return True return None def is_active(self, request: HttpRequest, read_only: bool = False) -> bool | None: if not self.pk: log_level = get_setting('LOG_MISSING_FLAGS') if log_level: logger.log(log_level, 'Flag %s not found', self.name) if get_setting('CREATE_MISSING_FLAGS'): flag, _created = get_waffle_flag_model().objects.get_or_create( name=self.name, defaults={ 'everyone': get_setting('FLAG_DEFAULT') } ) cache = get_cache() cache.set(self._cache_key(self.name), flag) return get_setting('FLAG_DEFAULT') if get_setting('OVERRIDE'): if self.name in request.GET: return request.GET[self.name] == '1' if self.everyone: return True elif self.everyone is False: return False if self.testing: # Testing mode is on. tc = get_setting('TEST_COOKIE') % self.name th = tc.replace('_', '-') on = None if tc in request.GET: on = request.GET[tc] == '1' elif th in request.headers: on = request.headers[th] == '1' if on is not None: if not hasattr(request, 'waffle_tests'): request.waffle_tests = {} request.waffle_tests[self.name] = on return on if tc in request.COOKIES: return request.COOKIES[tc] == 'True' active_for_language = self._is_active_for_language(request) if active_for_language is not None: return active_for_language active_for_user = self._is_active_for_user(request) if active_for_user is not None: return active_for_user if self.percent and self.percent > 0: if not hasattr(request, 'waffles'): request.waffles = {} elif self.name in request.waffles: return request.waffles[self.name][0] cookie = get_setting('COOKIE') % self.name if cookie in request.COOKIES: flag_active = request.COOKIES[cookie] == 'True' if not read_only: set_flag(request, self.name, flag_active, self.rollout) return flag_active if not read_only: if Decimal(str(random.uniform(0, 100))) <= self.percent: set_flag(request, self.name, True, self.rollout) return True set_flag(request, self.name, False, self.rollout) else: return None return False class AbstractUserFlag(AbstractBaseFlag): groups = models.ManyToManyField( Group, blank=True, help_text=_('Activate this flag for these user groups.'), verbose_name=_('Groups'), ) users = models.ManyToManyField( settings.AUTH_USER_MODEL, blank=True, help_text=_('Activate this flag for these users.'), verbose_name=_('Users'), ) class Meta(AbstractBaseFlag.Meta): abstract = True verbose_name = _('Flag') verbose_name_plural = _('Flags') def get_flush_keys(self, flush_keys: list[str] | None = None) -> list[str]: flush_keys = super().get_flush_keys(flush_keys) flush_keys.extend([ keyfmt(get_setting('FLAG_USERS_CACHE_KEY'), self.name), keyfmt(get_setting('FLAG_GROUPS_CACHE_KEY'), self.name), ]) return flush_keys def _get_user_ids(self) -> set[Any]: cache = get_cache() cache_key = keyfmt(get_setting('FLAG_USERS_CACHE_KEY'), self.name) cached = cache.get(cache_key) if cached == CACHE_EMPTY: return set() if cached: return cached user_ids = set(self.users.all().values_list('pk', flat=True)) if not user_ids: cache.add(cache_key, CACHE_EMPTY) return set() cache.add(cache_key, user_ids) return user_ids def _get_group_ids(self) -> set[Any]: cache = get_cache() cache_key = keyfmt(get_setting('FLAG_GROUPS_CACHE_KEY'), self.name) cached = cache.get(cache_key) if cached == CACHE_EMPTY: return set() if cached: return cached group_ids = set(self.groups.all().values_list('pk', flat=True)) if not group_ids: cache.add(cache_key, CACHE_EMPTY) return set() cache.add(cache_key, group_ids) return group_ids def is_active_for_user(self, user: AbstractBaseUser) -> bool | None: is_active = super().is_active_for_user(user) if is_active: return is_active user_ids = self._get_user_ids() if hasattr(user, 'pk') and user.pk in user_ids: return True if hasattr(user, 'groups'): group_ids = self._get_group_ids() if group_ids: user_groups = set(user.groups.all().values_list('pk', flat=True)) if group_ids.intersection(user_groups): return True return None class Flag(AbstractUserFlag): """A feature flag. Flags are active (or not) on a per-request basis. """ class Meta(AbstractUserFlag.Meta): swappable = 'WAFFLE_FLAG_MODEL' verbose_name = _('Flag') verbose_name_plural = _('Flags') class AbstractBaseSwitch(BaseModel): """A feature switch. Switches are active, or inactive, globally. """ name = models.CharField( max_length=100, unique=True, help_text=_('The human/computer readable name.'), verbose_name=_('Name'), ) active = models.BooleanField( default=False, help_text=_('Is this switch active?'), verbose_name=_('Active'), ) note = models.TextField( blank=True, help_text=_('Note where this Switch is used.'), verbose_name=_('Note'), ) created = models.DateTimeField( default=timezone.now, db_index=True, help_text=_('Date when this Switch was created.'), verbose_name=_('Created'), ) modified = models.DateTimeField( default=timezone.now, help_text=_('Date when this Switch was last modified.'), verbose_name=_('Modified'), ) objects = managers.SwitchManager() SINGLE_CACHE_KEY = 'SWITCH_CACHE_KEY' ALL_CACHE_KEY = 'ALL_SWITCHES_CACHE_KEY' class Meta: abstract = True verbose_name = _('Switch') verbose_name_plural = _('Switches') def is_active(self) -> bool: if not self.pk: log_level = get_setting('LOG_MISSING_SWITCHES') if log_level: logger.log(log_level, 'Switch %s not found', self.name) if get_setting('CREATE_MISSING_SWITCHES'): switch, _created = get_waffle_switch_model().objects.get_or_create( name=self.name, defaults={"active": get_setting("SWITCH_DEFAULT")} ) cache = get_cache() cache.set(self._cache_key(self.name), switch) return get_setting('SWITCH_DEFAULT') return self.active class AbstractBaseSample(BaseModel): """A sample of users. A sample is true some percentage of the time, but is not connected to users or requests. """ name = models.CharField( max_length=100, unique=True, help_text=_('The human/computer readable name.'), verbose_name=_('Name'), ) percent = models.DecimalField( max_digits=4, decimal_places=1, help_text=_('A number between 0.0 and 100.0 to indicate a percentage of the time ' 'this sample will be active.'), verbose_name=_('Percent'), ) note = models.TextField( blank=True, help_text=_('Note where this Sample is used.'), verbose_name=_('Note'), ) created = models.DateTimeField( default=timezone.now, db_index=True, help_text=_('Date when this Sample was created.'), verbose_name=_('Created'), ) modified = models.DateTimeField( default=timezone.now, help_text=_('Date when this Sample was last modified.'), verbose_name=_('Modified'), ) objects = managers.SampleManager() SINGLE_CACHE_KEY = 'SAMPLE_CACHE_KEY' ALL_CACHE_KEY = 'ALL_SAMPLES_CACHE_KEY' class Meta: abstract = True verbose_name = _('Sample') verbose_name_plural = _('Samples') def is_active(self) -> bool: if not self.pk: log_level = get_setting('LOG_MISSING_SAMPLES') if log_level: logger.log(log_level, 'Sample %s not found', self.name) if get_setting('CREATE_MISSING_SAMPLES'): default_percent = 100 if get_setting('SAMPLE_DEFAULT') else 0 sample, _created = get_waffle_sample_model().objects.get_or_create( name=self.name, defaults={"percent": default_percent} ) cache = get_cache() cache.set(self._cache_key(self.name), sample) return get_setting('SAMPLE_DEFAULT') return Decimal(str(random.uniform(0, 100))) <= self.percent class Switch(AbstractBaseSwitch): """A feature switch. Switches are active, or inactive, globally. """ class Meta(AbstractBaseSwitch.Meta): swappable = 'WAFFLE_SWITCH_MODEL' verbose_name = _('Switch') verbose_name_plural = _('Switches') class Sample(AbstractBaseSample): """A sample of users. A sample is true some percentage of the time, but is not connected to users or requests. """ class Meta(AbstractBaseSample.Meta): swappable = 'WAFFLE_SAMPLE_MODEL' verbose_name = _('Sample') verbose_name_plural = _('Samples') django-waffle-4.2.0/waffle/py.typed000066400000000000000000000000001471570242400171600ustar00rootroot00000000000000django-waffle-4.2.0/waffle/signals.py000066400000000000000000000013731471570242400175110ustar00rootroot00000000000000from django.db.models.signals import m2m_changed from django.dispatch import receiver from waffle import get_waffle_flag_model @receiver(m2m_changed, sender=get_waffle_flag_model().users.through) @receiver(m2m_changed, sender=get_waffle_flag_model().groups.through) def flag_membership_changed(sender, instance, action, **kwargs): if action in ('post_add', 'post_remove'): flag_model = get_waffle_flag_model() # instance could be a flag or an instance of the related model # https://docs.djangoproject.com/en/dev/ref/signals/#m2m-changed if isinstance(instance, flag_model): instance.flush() else: for flag in flag_model.objects.filter(pk__in=kwargs['pk_set']): flag.flush() django-waffle-4.2.0/waffle/templates/000077500000000000000000000000001471570242400174715ustar00rootroot00000000000000django-waffle-4.2.0/waffle/templates/waffle/000077500000000000000000000000001471570242400207355ustar00rootroot00000000000000django-waffle-4.2.0/waffle/templates/waffle/waffle.js000066400000000000000000000023421471570242400225400ustar00rootroot00000000000000(function(){ var FLAGS = { {% for flag, value in flags %}'{{ flag }}': {% if value %}true{% else %}false{% endif %}{% if not forloop.last %},{% endif %}{% endfor %} }, SWITCHES = { {% for switch, value in switches %}'{{ switch }}': {% if value %}true{% else %}false{% endif %}{% if not forloop.last %},{% endif %}{% endfor %} }, SAMPLES = { {% for sample, value in samples %}'{{ sample }}': {% if value %}true{% else %}false{% endif %}{% if not forloop.last %},{% endif %}{% endfor %} }; window.waffle = { "flag_is_active": function waffle_flag(flag_name) { {% if flag_default %} if(FLAGS[flag_name] === undefined) return true; {% endif %} return !!FLAGS[flag_name]; }, "switch_is_active": function waffle_switch(switch_name) { {% if switch_default %} if(SWITCHES[switch_name] === undefined) return true; {% endif %} return !!SWITCHES[switch_name]; }, "sample_is_active": function waffle_sample(sample_name) { {% if sample_default %} if(SAMPLES[sample_name] === undefined) return true; {% endif %} return !!SAMPLES[sample_name]; }, "FLAGS": FLAGS, "SWITCHES": SWITCHES, "SAMPLES": SAMPLES }; })(); django-waffle-4.2.0/waffle/templatetags/000077500000000000000000000000001471570242400201655ustar00rootroot00000000000000django-waffle-4.2.0/waffle/templatetags/__init__.py000066400000000000000000000000001471570242400222640ustar00rootroot00000000000000django-waffle-4.2.0/waffle/templatetags/waffle_tags.py000066400000000000000000000047021471570242400230240ustar00rootroot00000000000000from django import template from django.template.base import VariableDoesNotExist from waffle import flag_is_active, sample_is_active, switch_is_active from waffle.views import _generate_waffle_js register = template.Library() class WaffleNode(template.Node): child_nodelists = ('nodelist_true', 'nodelist_false') def __init__(self, nodelist_true, nodelist_false, condition, name, compiled_name): self.nodelist_true = nodelist_true self.nodelist_false = nodelist_false self.condition = condition self.name = name self.compiled_name = compiled_name def __repr__(self): return f'' def __iter__(self): yield from self.nodelist_true yield from self.nodelist_false def render(self, context): try: name = self.compiled_name.resolve(context) except VariableDoesNotExist: name = self.name if not name: name = self.name if self.condition(context.get('request', None), name): return self.nodelist_true.render(context) return self.nodelist_false.render(context) @classmethod def handle_token(cls, parser, token, kind, condition): bits = token.split_contents() if len(bits) < 2: raise template.TemplateSyntaxError(f"{bits[0]!r} tag requires an argument") name = bits[1] compiled_name = parser.compile_filter(name) nodelist_true = parser.parse(('else', f'end{kind}')) token = parser.next_token() if token.contents == 'else': nodelist_false = parser.parse((f'end{kind}',)) parser.delete_first_token() else: nodelist_false = template.NodeList() return cls(nodelist_true, nodelist_false, condition, name, compiled_name) @register.tag def flag(parser, token): return WaffleNode.handle_token(parser, token, 'flag', flag_is_active) @register.tag def switch(parser, token): return WaffleNode.handle_token(parser, token, 'switch', lambda request, name: switch_is_active(name)) @register.tag def sample(parser, token): return WaffleNode.handle_token(parser, token, 'sample', lambda request, name: sample_is_active(name)) class InlineWaffleJSNode(template.Node): def render(self, context): return _generate_waffle_js(context['request']) @register.tag def wafflejs(parser, token): return InlineWaffleJSNode() django-waffle-4.2.0/waffle/tests/000077500000000000000000000000001471570242400166355ustar00rootroot00000000000000django-waffle-4.2.0/waffle/tests/__init__.py000066400000000000000000000000001471570242400207340ustar00rootroot00000000000000django-waffle-4.2.0/waffle/tests/base.py000066400000000000000000000011731471570242400201230ustar00rootroot00000000000000from django import test from django.core import cache class TestCase(test.TransactionTestCase): def _pre_setup(self): cache.cache.clear() super()._pre_setup() class ReplicationRouter: """Router for simulating an environment with DB replication This router directs all DB reads to a completely different database than writes. This can be useful for simulating an environment where DB replication is delayed to identify potential race conditions. """ def db_for_read(self, model, **hints): return 'readonly' def db_for_write(self, model, **hints): return 'default' django-waffle-4.2.0/waffle/tests/test_admin.py000077500000000000000000000157551471570242400213560ustar00rootroot00000000000000from unittest import mock import unittest import django from django.contrib.admin.models import LogEntry, CHANGE, DELETION from django.contrib.admin.sites import AdminSite from django.contrib.auth import get_user_model from django.contrib.auth.models import Permission from django.test.utils import override_settings from waffle import get_waffle_flag_model from waffle.admin import (FlagAdmin, SwitchAdmin, InformativeManyToManyRawIdWidget, enable_for_all, disable_for_all, delete_individually, enable_switches, disable_switches) from waffle.models import Switch from waffle.tests.base import TestCase from waffle.utils import get_setting django_version = tuple(int(d) for d in django.get_version().split(".")) class FakeSuperUser: def has_perm(self, perm): return True class FakeRequest: def __init__(self): self.GET = {} self.user = get_user_model().objects.create(username="test1") Flag = get_waffle_flag_model() skip_if_admin_permissions_not_available = \ unittest.skipIf(django_version < (2, 1, 0), "Feature not available") class FlagAdminTests(TestCase): def setUp(self): self.site = AdminSite() self.flag_admin = FlagAdmin(Flag, self.site) def test_informative_widget(self): request = mock.Mock() request.has_perm = lambda self, perm: True form = self.flag_admin.get_form(request)() user_widget = form.fields["users"].widget self.assertIsInstance(user_widget, InformativeManyToManyRawIdWidget) user1 = get_user_model().objects.create(username="test1") user2 = get_user_model().objects.create(username="test2") self.assertIn("(test1, test2)", user_widget.render("users", [user1.pk, user2.pk])) def test_enable_for_all(self): f1 = Flag.objects.create(name="flag1", everyone=False) request = FakeRequest() enable_for_all(None, request, Flag.objects.all()) f1.refresh_from_db() self.assertTrue(f1.everyone) log_entry = LogEntry.objects.get(user=request.user) self.assertEqual(log_entry.action_flag, CHANGE) self.assertEqual(log_entry.object_repr, "flag1 on") def test_disable_for_all(self): f1 = Flag.objects.create(name="flag1", everyone=True) request = FakeRequest() disable_for_all(None, request, Flag.objects.all()) f1.refresh_from_db() self.assertFalse(f1.everyone) log_entry = LogEntry.objects.get(user=request.user) self.assertEqual(log_entry.action_flag, CHANGE) self.assertEqual(log_entry.object_repr, "flag1 off") def test_delete_individually(self): Flag.objects.create(name="flag1", everyone=True) request = FakeRequest() delete_individually(None, request, Flag.objects.all()) self.assertIsNone(Flag.objects.first()) log_entry = LogEntry.objects.get(user=request.user) self.assertEqual(log_entry.action_flag, DELETION) @skip_if_admin_permissions_not_available def test_flag_no_actions_without_permissions(self): request = FakeRequest() actions = self.flag_admin.get_actions(request) self.assertEqual(actions.keys(), set()) @skip_if_admin_permissions_not_available def test_flag_action_change(self): request = FakeRequest() request.user.user_permissions.add(Permission.objects.get(codename="change_flag")) actions = self.flag_admin.get_actions(request) self.assertEqual(actions.keys(), {"enable_for_all", "disable_for_all"}) @skip_if_admin_permissions_not_available def test_flag_action_delete(self): request = FakeRequest() request.user.user_permissions.add(Permission.objects.get(codename="delete_flag")) actions = self.flag_admin.get_actions(request) self.assertEqual(actions.keys(), {"delete_individually"}) def test_model_can_be_registered_by_default(self): config = get_setting("ENABLE_ADMIN_PAGES") _register_model_to_admin_site(admin_site=self.site, config_setting=config, model=Flag) self.assertTrue(self.site.is_registered(Flag)) @override_settings(WAFFLE_ENABLE_ADMIN_PAGES=False) def test_admin_page_can_be_disabled(self): config = get_setting("ENABLE_ADMIN_PAGES") _register_model_to_admin_site(admin_site=self.site, config_setting=config, model=Flag) self.assertFalse(self.site.is_registered(Flag)) class SwitchAdminTests(TestCase): def setUp(self): self.site = AdminSite() self.switch_admin = SwitchAdmin(Switch, self.site) def test_enable_switches(self): s1 = Switch.objects.create(name="switch1", active=False) request = FakeRequest() enable_switches(None, request, Switch.objects.all()) s1.refresh_from_db() self.assertTrue(s1.active) log_entry = LogEntry.objects.get(user=request.user) self.assertEqual(log_entry.action_flag, CHANGE) self.assertEqual(log_entry.object_repr, "switch1 on") def test_disable_switches(self): s1 = Switch.objects.create(name="switch1", active=True) request = FakeRequest() disable_switches(None, request, Switch.objects.all()) s1.refresh_from_db() self.assertFalse(s1.active) log_entry = LogEntry.objects.get(user=request.user) self.assertEqual(log_entry.action_flag, CHANGE) self.assertEqual(log_entry.object_repr, "switch1 off") @skip_if_admin_permissions_not_available def test_switch_no_actions_without_permissions(self): request = FakeRequest() actions = self.switch_admin.get_actions(request) self.assertEqual(actions.keys(), set()) @skip_if_admin_permissions_not_available def test_switch_action_change(self): request = FakeRequest() request.user.user_permissions.add(Permission.objects.get(codename="change_switch")) actions = self.switch_admin.get_actions(request) self.assertEqual(actions.keys(), {"enable_switches", "disable_switches"}) @skip_if_admin_permissions_not_available def test_switch_action_delete(self): request = FakeRequest() request.user.user_permissions.add(Permission.objects.get(codename="delete_switch")) actions = self.switch_admin.get_actions(request) self.assertEqual(actions.keys(), {"delete_individually"}) def test_model_can_be_registered_by_default(self): config = get_setting("ENABLE_ADMIN_PAGES") _register_model_to_admin_site(admin_site=self.site, config_setting=config, model=Switch) self.assertTrue(self.site.is_registered(Switch)) @override_settings(WAFFLE_ENABLE_ADMIN_PAGES=False) def test_admin_page_can_be_disabled(self): config = get_setting("ENABLE_ADMIN_PAGES") _register_model_to_admin_site(admin_site=self.site, config_setting=config, model=Switch) self.assertFalse(self.site.is_registered(Switch)) def _register_model_to_admin_site(admin_site, config_setting, model): if config_setting: admin_site.register(model) django-waffle-4.2.0/waffle/tests/test_decorators.py000066400000000000000000000122461471570242400224200ustar00rootroot00000000000000from waffle import get_waffle_flag_model, get_waffle_switch_model from waffle.tests.base import TestCase class DecoratorTests(TestCase): def test_flag_must_be_active(self): resp = self.client.get('/flag-on') self.assertEqual(404, resp.status_code) get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flag-on') self.assertEqual(200, resp.status_code) def test_flag_must_be_inactive(self): resp = self.client.get('/flag-off') self.assertEqual(200, resp.status_code) get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flag-off') self.assertEqual(404, resp.status_code) def test_switch_must_be_active(self): resp = self.client.get('/switch-on') self.assertEqual(404, resp.status_code) get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switch-on') self.assertEqual(200, resp.status_code) def test_switch_must_be_inactive(self): resp = self.client.get('/switch-off') self.assertEqual(200, resp.status_code) get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switch-off') self.assertEqual(404, resp.status_code) def test_switch_must_be_inactive_and_redirect_to_view(self): resp = self.client.get('/switched_view_with_valid_redirect') self.assertEqual(302, resp.status_code) get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switched_view_with_valid_redirect') self.assertEqual(200, resp.status_code) def test_switch_must_be_inactive_and_redirect_to_named_view(self): resp = self.client.get('/switched_view_with_valid_url_name') self.assertEqual(302, resp.status_code) get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switched_view_with_valid_url_name') self.assertEqual(200, resp.status_code) def test_switch_must_be_inactive_and_redirect_to_view_with_args(self): resp = self.client.get('/switched_view_with_args_with_valid_redirect/1/') self.assertRedirects(resp, '/foo_view_with_args/1/') get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switched_view_with_args_with_valid_redirect/1/') self.assertEqual(200, resp.status_code) def test_switch_must_be_inactive_and_redirect_to_named_view_with_args(self): resp = self.client.get('/switched_view_with_args_with_valid_url_name/1/') self.assertRedirects(resp, '/foo_view_with_args/1/') get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switched_view_with_args_with_valid_url_name/1/') self.assertEqual(200, resp.status_code) def test_switch_must_be_inactive_and_not_redirect(self): resp = self.client.get('/switched_view_with_invalid_redirect') self.assertEqual(404, resp.status_code) get_waffle_switch_model().objects.create(name='foo', active=True) resp = self.client.get('/switched_view_with_invalid_redirect') self.assertEqual(200, resp.status_code) def test_flag_must_be_inactive_and_redirect_to_view(self): resp = self.client.get('/flagged_view_with_valid_redirect') self.assertEqual(302, resp.status_code) get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flagged_view_with_valid_redirect') self.assertEqual(200, resp.status_code) def test_flag_must_be_inactive_and_redirect_to_named_view(self): resp = self.client.get('/flagged_view_with_valid_url_name') self.assertEqual(302, resp.status_code) get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flagged_view_with_valid_url_name') self.assertEqual(200, resp.status_code) def test_flag_must_be_inactive_and_redirect_to_view_with_args(self): resp = self.client.get('/flagged_view_with_args_with_valid_redirect/1/') self.assertRedirects(resp, '/foo_view_with_args/1/') get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flagged_view_with_args_with_valid_redirect/1/') self.assertEqual(200, resp.status_code) def test_flag_must_be_inactive_and_redirect_to_named_view_with_args(self): resp = self.client.get('/flagged_view_with_args_with_valid_url_name/1/') self.assertRedirects(resp, '/foo_view_with_args/1/') get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flagged_view_with_args_with_valid_url_name/1/') self.assertEqual(200, resp.status_code) def test_flag_must_be_inactive_and_not_redirect(self): resp = self.client.get('/flagged_view_with_invalid_redirect') self.assertEqual(404, resp.status_code) get_waffle_flag_model().objects.create(name='foo', everyone=True) resp = self.client.get('/flagged_view_with_invalid_redirect') self.assertEqual(200, resp.status_code) django-waffle-4.2.0/waffle/tests/test_management.py000066400000000000000000000314061471570242400223660ustar00rootroot00000000000000import io from django.core.management import call_command, CommandError from django.contrib.auth.models import Group, User from waffle import ( get_waffle_flag_model, get_waffle_switch_model, get_waffle_sample_model, ) from waffle.tests.base import TestCase class WaffleFlagManagementCommandTests(TestCase): def test_create(self): """ The command should create a new flag. """ name = 'test' percent = 20 Group.objects.create(name='waffle_group') call_command('waffle_flag', name, percent=percent, testing=True, superusers=True, staff=True, authenticated=True, rollout=True, create=True, group=['waffle_group']) flag = get_waffle_flag_model().objects.get(name=name) self.assertEqual(flag.percent, percent) self.assertIsNone(flag.everyone) self.assertTrue(flag.testing) self.assertTrue(flag.superusers) self.assertTrue(flag.staff) self.assertTrue(flag.authenticated) self.assertTrue(flag.rollout) self.assertEqual(list(flag.groups.values_list('name', flat=True)), ['waffle_group']) def test_not_create(self): """ The command shouldn't create a new flag if the create flag is not set. """ name = 'test' with self.assertRaisesRegex(CommandError, 'This flag does not exist.'): call_command('waffle_flag', name, everyone=True, percent=20, superusers=True, staff=True, authenticated=True, rollout=True) self.assertFalse(get_waffle_flag_model().objects.filter(name=name).exists()) def test_update(self): """ The command should update an existing flag. """ name = 'test' flag = get_waffle_flag_model().objects.create(name=name) self.assertIsNone(flag.percent) self.assertIsNone(flag.everyone) self.assertTrue(flag.superusers) self.assertFalse(flag.staff) self.assertFalse(flag.authenticated) self.assertFalse(flag.rollout) percent = 30 call_command('waffle_flag', name, percent=percent, superusers=False, staff=True, authenticated=True, rollout=True) flag.refresh_from_db() self.assertEqual(flag.percent, percent) self.assertIsNone(flag.everyone) self.assertFalse(flag.superusers) self.assertTrue(flag.staff) self.assertTrue(flag.authenticated) self.assertTrue(flag.rollout) def test_update_activate_everyone(self): """ The command should update everyone field to True """ name = 'test' flag = get_waffle_flag_model().objects.create(name=name) self.assertIsNone(flag.percent) self.assertIsNone(flag.everyone) self.assertTrue(flag.superusers) self.assertFalse(flag.staff) self.assertFalse(flag.authenticated) self.assertFalse(flag.rollout) percent = 30 call_command('waffle_flag', name, everyone=True, percent=percent, superusers=False, staff=True, authenticated=True, rollout=True) flag.refresh_from_db() self.assertEqual(flag.percent, percent) self.assertTrue(flag.everyone) self.assertFalse(flag.superusers) self.assertTrue(flag.staff) self.assertTrue(flag.authenticated) self.assertTrue(flag.rollout) def test_update_deactivate_everyone(self): """ The command should update everyone field to False""" name = 'test' flag = get_waffle_flag_model().objects.create(name=name) self.assertIsNone(flag.percent) self.assertIsNone(flag.everyone) self.assertTrue(flag.superusers) self.assertFalse(flag.staff) self.assertFalse(flag.authenticated) self.assertFalse(flag.rollout) percent = 30 call_command('waffle_flag', name, everyone=False, percent=percent, superusers=False, staff=True, authenticated=True, rollout=True) flag.refresh_from_db() self.assertEqual(flag.percent, percent) self.assertFalse(flag.everyone) self.assertFalse(flag.superusers) self.assertTrue(flag.staff) self.assertTrue(flag.authenticated) self.assertTrue(flag.rollout) def test_list(self): """ The command should list all flags.""" stdout = io.StringIO() get_waffle_flag_model().objects.create(name='test') call_command('waffle_flag', list_flags=True, stdout=stdout) expected = 'Flags:\nNAME: test\nSUPERUSERS: True\nEVERYONE: None\n' \ 'AUTHENTICATED: False\nPERCENT: None\nTESTING: False\n' \ 'ROLLOUT: False\nSTAFF: False\nGROUPS: []\nUSERS: []' actual = stdout.getvalue().strip() self.assertEqual(actual, expected) def test_group_append(self): """ The command should append a group to a flag.""" original_group = Group.objects.create(name='waffle_group') Group.objects.create(name='append_group') flag = get_waffle_flag_model().objects.create(name='test') flag.groups.add(original_group) flag.refresh_from_db() self.assertEqual(list(flag.groups.values_list('name', flat=True)), ['waffle_group']) call_command('waffle_flag', 'test', group=['append_group'], append=True) flag.refresh_from_db() self.assertEqual(list(flag.groups.values_list('name', flat=True)), ['waffle_group', 'append_group']) self.assertIsNone(flag.everyone) def test_user(self): """ The command should replace a user to a flag.""" original_user = User.objects.create_user('waffle_test') User.objects.create_user('add_user') flag = get_waffle_flag_model().objects.create(name='test') flag.users.add(original_user) flag.refresh_from_db() self.assertEqual(list(flag.users.values_list('username', flat=True)), ['waffle_test']) call_command('waffle_flag', 'test', user=['add_user']) flag.refresh_from_db() self.assertEqual(list(flag.users.values_list('username', flat=True)), ['add_user']) self.assertIsNone(flag.everyone) def test_user_append(self): """ The command should append a user to a flag.""" original_user = User.objects.create_user('waffle_test') User.objects.create_user('append_user') User.objects.create_user('append_user_email', email='test@example.com') flag = get_waffle_flag_model().objects.create(name='test') flag.users.add(original_user) flag.refresh_from_db() self.assertEqual(list(flag.users.values_list('username', flat=True)), ['waffle_test']) call_command('waffle_flag', 'test', user=['append_user'], append=True) flag.refresh_from_db() self.assertEqual(list(flag.users.values_list('username', flat=True)), ['waffle_test', 'append_user']) self.assertIsNone(flag.everyone) call_command('waffle_flag', 'test', user=['test@example.com'], append=True) flag.refresh_from_db() self.assertEqual(list(flag.users.values_list('username', flat=True)), ['waffle_test', 'append_user', 'append_user_email']) self.assertIsNone(flag.everyone) class WaffleSampleManagementCommandTests(TestCase): def test_create(self): """ The command should create a new sample. """ name = 'test' percent = 20 call_command('waffle_sample', name, str(percent), create=True) sample = get_waffle_sample_model().objects.get(name=name) self.assertEqual(sample.percent, percent) def test_not_create(self): """ The command shouldn't create a new sample if the create flag is not set. """ name = 'test' with self.assertRaisesRegex(CommandError, 'This sample does not exist'): call_command('waffle_sample', name, '20') self.assertFalse(get_waffle_sample_model().objects.filter(name=name).exists()) def test_update(self): """ The command should update an existing sample. """ name = 'test' sample = get_waffle_sample_model().objects.create(name=name, percent=0) self.assertEqual(sample.percent, 0) percent = 50 call_command('waffle_sample', name, str(percent)) sample.refresh_from_db() self.assertEqual(sample.percent, percent) def test_list(self): """ The command should list all samples.""" stdout = io.StringIO() get_waffle_sample_model().objects.create(name='test', percent=34) call_command('waffle_sample', list_samples=True, stdout=stdout) expected = 'Samples:\ntest: 34.0%' actual = stdout.getvalue().strip() self.assertEqual(actual, expected) class WaffleSwitchManagementCommandTests(TestCase): def test_create(self): """ The command should create a new switch. """ name = 'test' call_command('waffle_switch', name, 'on', create=True) switch = get_waffle_switch_model().objects.get(name=name, active=True) switch.delete() call_command('waffle_switch', name, 'off', create=True) get_waffle_switch_model().objects.get(name=name, active=False) def test_not_create(self): """ The command shouldn't create a new switch if the create flag is not set. """ name = 'test' with self.assertRaisesRegex(CommandError, 'This switch does not exist.'): call_command('waffle_switch', name, 'on') self.assertFalse(get_waffle_switch_model().objects.filter(name=name).exists()) def test_update(self): """ The command should update an existing switch. """ name = 'test' switch = get_waffle_switch_model().objects.create(name=name, active=True) call_command('waffle_switch', name, 'off') switch.refresh_from_db() self.assertFalse(switch.active) call_command('waffle_switch', name, 'on') switch.refresh_from_db() self.assertTrue(switch.active) def test_list(self): """ The command should list all switches.""" stdout = io.StringIO() get_waffle_switch_model().objects.create(name='switch1', active=True) get_waffle_switch_model().objects.create(name='switch2', active=False) call_command('waffle_switch', list_switches=True, stdout=stdout) expected = 'Switches:\nswitch1: on\nswitch2: off' actual = stdout.getvalue().strip() self.assertEqual(actual, expected) class WaffleDeleteManagementCommandTests(TestCase): def test_delete_flag(self): """ The command should delete a flag. """ name = 'test_flag' get_waffle_flag_model().objects.create(name=name) call_command('waffle_delete', flag_names=[name]) self.assertEqual(get_waffle_flag_model().objects.count(), 0) def test_delete_swtich(self): """ The command should delete a switch. """ name = 'test_switch' get_waffle_switch_model().objects.create(name=name) call_command('waffle_delete', switch_names=[name]) self.assertEqual(get_waffle_switch_model().objects.count(), 0) def test_delete_sample(self): """ The command should delete a sample. """ name = 'test_sample' get_waffle_sample_model().objects.create(name=name, percent=0) call_command('waffle_delete', sample_names=[name]) self.assertEqual(get_waffle_sample_model().objects.count(), 0) def test_delete_mix_of_types(self): """ The command should delete different types of records. """ name = 'test' get_waffle_flag_model().objects.create(name=name) get_waffle_switch_model().objects.create(name=name) get_waffle_sample_model().objects.create(name=name, percent=0) call_command('waffle_delete', switch_names=[name], flag_names=[name], sample_names=[name]) self.assertEqual(get_waffle_flag_model().objects.count(), 0) self.assertEqual(get_waffle_switch_model().objects.count(), 0) self.assertEqual(get_waffle_sample_model().objects.count(), 0) def test_delete_some_but_not_all_records(self): """ The command should delete specified records, but leave records not specified alone. """ flag_1 = 'test_flag_1' flag_2 = 'test_flag_2' get_waffle_flag_model().objects.create(name=flag_1) get_waffle_flag_model().objects.create(name=flag_2) call_command('waffle_delete', flag_names=[flag_1]) self.assertTrue(get_waffle_flag_model().objects.filter(name=flag_2).exists()) django-waffle-4.2.0/waffle/tests/test_middleware.py000066400000000000000000000030461471570242400223660ustar00rootroot00000000000000from django.http import HttpResponse from django.test import RequestFactory from waffle.middleware import WaffleMiddleware get = RequestFactory().get('/foo') def test_set_cookies(): get.waffles = {'foo': [True, False], 'bar': [False, False]} resp = HttpResponse() assert 'dwf_foo' not in resp.cookies assert 'dwf_bar' not in resp.cookies resp = WaffleMiddleware().process_response(get, resp) assert 'dwf_foo' in resp.cookies assert 'dwf_bar' in resp.cookies assert 'True' == resp.cookies['dwf_foo'].value assert 'False' == resp.cookies['dwf_bar'].value def test_rollout_cookies(): get.waffles = {'foo': [True, True], 'bar': [False, True], 'baz': [True, False], 'qux': [False, False]} resp = HttpResponse() resp = WaffleMiddleware().process_response(get, resp) for k in get.waffles: cookie = f'dwf_{k}' assert cookie in resp.cookies assert str(get.waffles[k][0]) == resp.cookies[cookie].value if get.waffles[k][1]: assert bool(resp.cookies[cookie]['max-age']) == get.waffles[k][0] else: assert resp.cookies[cookie]['max-age'] def test_testing_cookies(): get.waffles = {} get.waffle_tests = {'foo': True, 'bar': False} resp = HttpResponse() resp = WaffleMiddleware().process_response(get, resp) for k in get.waffle_tests: cookie = f'dwft_{k}' assert str(get.waffle_tests[k]) == resp.cookies[cookie].value assert not resp.cookies[cookie]['max-age'] django-waffle-4.2.0/waffle/tests/test_mixin.py000066400000000000000000000071021471570242400213720ustar00rootroot00000000000000from django.contrib.auth.models import AnonymousUser from django.http import Http404 from django.test import RequestFactory from test_app import views from waffle.middleware import WaffleMiddleware from waffle.models import Flag, Sample, Switch from waffle.tests.base import TestCase def get(**kw): request = RequestFactory().get('/foo', data=kw) request.user = AnonymousUser() return request def get_response(request): return 'hello' def process_request(request, view): response = view.as_view()(request) return WaffleMiddleware(get_response).process_response(request, response) class WaffleFlagMixinTest(TestCase): def setUp(self): self.request = get() def test_flag_must_be_active(self): view = views.FlagView self.assertRaises(Http404, process_request, self.request, view) Flag.objects.create(name='foo', everyone=True) response = process_request(self.request, view) self.assertEqual(b'foo', response.content) def test_flag_must_be_inactive(self): view = views.FlagOffView response = process_request(self.request, view) self.assertEqual(b'foo', response.content) Flag.objects.create(name='foo', everyone=True) self.assertRaises(Http404, process_request, self.request, view) def test_override_with_cookie(self): Flag.objects.create(name='foo', percent='0.1') self.request.COOKIES['dwf_foo'] = 'True' response = process_request(self.request, views.FlagView) self.assertEqual(b'foo', response.content) self.assertIn('dwf_foo', response.cookies) self.assertEqual('True', response.cookies['dwf_foo'].value) class WaffleSampleMixinTest(TestCase): def setUp(self): self.request = get() def test_sample_must_be_active(self): view = views.SampleView self.assertRaises(Http404, process_request, self.request, view) Sample.objects.create(name='foo', percent='100.0') response = process_request(self.request, view) self.assertEqual(b'foo', response.content) def test_sample_must_be_inactive(self): view = views.SampleOffView response = process_request(self.request, view) self.assertEqual(b'foo', response.content) Sample.objects.create(name='foo', percent='100.0') self.assertRaises(Http404, process_request, self.request, view) def test_override_with_cookie(self): Sample.objects.create(name='foo', percent='0.0') self.request.COOKIES['dwf_foo'] = 'True' self.assertRaises(Http404, process_request, self.request, views.SwitchView) class WaffleSwitchMixinTest(TestCase): def setUp(self): self.request = get() def test_switch_must_be_active(self): view = views.SwitchView self.assertRaises(Http404, process_request, self.request, view) Switch.objects.create(name='foo', active=True) response = process_request(self.request, view) self.assertEqual(b'foo', response.content) def test_switch_must_be_inactive(self): view = views.SwitchOffView response = process_request(self.request, view) self.assertEqual(b'foo', response.content) Switch.objects.create(name='foo', active=True) self.assertRaises(Http404, process_request, self.request, view) def test_no_override_with_cookie(self): Switch.objects.create(name='foo', active=False) self.request.COOKIES['dwf_foo'] = 'True' self.assertRaises(Http404, process_request, self.request, views.SwitchView) django-waffle-4.2.0/waffle/tests/test_models.py000066400000000000000000000026651471570242400215420ustar00rootroot00000000000000from django.test import TestCase from waffle import ( get_waffle_flag_model, get_waffle_sample_model, get_waffle_switch_model, ) from django.contrib.auth.models import User class ModelsTests(TestCase): def test_natural_keys(self): flag = get_waffle_flag_model().objects.create(name='test-flag') switch = get_waffle_switch_model().objects.create(name='test-switch') sample = get_waffle_sample_model().objects.create(name='test-sample', percent=0) self.assertEqual(flag.natural_key(), ('test-flag',)) self.assertEqual(switch.natural_key(), ('test-switch',)) self.assertEqual(sample.natural_key(), ('test-sample',)) self.assertEqual( get_waffle_flag_model().objects.get_by_natural_key("test-flag"), flag ) self.assertEqual( get_waffle_switch_model().objects.get_by_natural_key("test-switch"), switch ) self.assertEqual( get_waffle_sample_model().objects.get_by_natural_key("test-sample"), sample ) def test_flag_is_not_active_for_none_requests(self): flag = get_waffle_flag_model().objects.create(name='test-flag') self.assertEqual(flag.is_active(None), False) def test_is_active_for_user_when_everyone_is_active(self): flag = get_waffle_flag_model().objects.create(name='test-flag') flag.everyone = True self.assertEqual(flag.is_active_for_user(User()), True) django-waffle-4.2.0/waffle/tests/test_templates.py000066400000000000000000000045121471570242400222460ustar00rootroot00000000000000from unittest import skipUnless from django.conf import settings from django.contrib.auth.models import AnonymousUser from django.template import Template from django.template.base import VariableNode from django.test import RequestFactory from test_app import views from waffle.middleware import WaffleMiddleware from waffle.tests.base import TestCase def get(): request = RequestFactory().get('/foo') request.user = AnonymousUser() return request def get_response(request): return 'hello' def process_request(request, view): response = view(request) return WaffleMiddleware(get_response).process_response(request, response) class WaffleTemplateTests(TestCase): def test_django_tags(self): request = get() response = process_request(request, views.flag_in_django) self.assertContains(response, 'flag off') self.assertContains(response, 'switch off') self.assertContains(response, 'sample') self.assertContains(response, 'flag_var off') self.assertContains(response, 'switch_var off') self.assertContains(response, 'sample_var') self.assertContains(response, 'window.waffle =') def test_get_nodes_by_type(self): """WaffleNode.get_nodes_by_type() should find all child nodes.""" test_template = Template( '{% load waffle_tags %}' '{% switch "x" %}' '{{ a }}' '{% else %}' '{{ b }}' '{% endswitch %}' ) children = test_template.nodelist.get_nodes_by_type(VariableNode) self.assertEqual(len(children), 2) def test_no_request_context(self): """Switches and Samples shouldn't require a request context.""" request = get() content = process_request(request, views.no_request_context) assert 'switch off' in content assert 'sample' in content @skipUnless( settings.JINJA_INSTALLED, "django-jinja is currently unmaintained and uncompatible with django >= 3.0" ) def test_jinja_tags(self): request = get() response = process_request(request, views.flag_in_jinja) self.assertContains(response, 'flag off') self.assertContains(response, 'switch off') self.assertContains(response, 'sample') self.assertContains(response, 'window.waffle =') django-waffle-4.2.0/waffle/tests/test_testutils.py000066400000000000000000000302301471570242400223040ustar00rootroot00000000000000from decimal import Decimal from django.contrib.auth.models import AnonymousUser from django.db import transaction from django.test import TransactionTestCase, RequestFactory, TestCase import waffle from waffle.testutils import override_switch, override_flag, override_sample class OverrideSwitchMixin: def test_switch_existed_and_was_active(self): waffle.get_waffle_switch_model().objects.create(name='foo', active=True) with override_switch('foo', active=True): assert waffle.switch_is_active('foo') with override_switch('foo', active=False): assert not waffle.switch_is_active('foo') # make sure it didn't change 'active' value assert waffle.get_waffle_switch_model().objects.get(name='foo').active def test_switch_existed_and_was_NOT_active(self): waffle.get_waffle_switch_model().objects.create(name='foo', active=False) with override_switch('foo', active=True): assert waffle.switch_is_active('foo') with override_switch('foo', active=False): assert not waffle.switch_is_active('foo') # make sure it didn't change 'active' value assert not waffle.get_waffle_switch_model().objects.get(name='foo').active def test_new_switch(self): assert not waffle.get_waffle_switch_model().objects.filter(name='foo').exists() with override_switch('foo', active=True): assert waffle.switch_is_active('foo') with override_switch('foo', active=False): assert not waffle.switch_is_active('foo') assert not waffle.get_waffle_switch_model().objects.filter(name='foo').exists() def test_as_decorator(self): assert not waffle.get_waffle_switch_model().objects.filter(name='foo').exists() @override_switch('foo', active=True) def test_enabled(): assert waffle.switch_is_active('foo') test_enabled() @override_switch('foo', active=False) def test_disabled(): assert not waffle.switch_is_active('foo') test_disabled() assert not waffle.get_waffle_switch_model().objects.filter(name='foo').exists() def test_restores_after_exception(self): waffle.get_waffle_switch_model().objects.create(name='foo', active=True) def inner(): with override_switch('foo', active=False): raise RuntimeError("Trying to break") with self.assertRaises(RuntimeError): inner() assert waffle.get_waffle_switch_model().objects.get(name='foo').active def test_restores_after_exception_in_decorator(self): waffle.get_waffle_switch_model().objects.create(name='foo', active=True) @override_switch('foo', active=False) def inner(): raise RuntimeError("Trying to break") with self.assertRaises(RuntimeError): inner() assert waffle.get_waffle_switch_model().objects.get(name='foo').active def test_cache_is_flushed_by_testutils_even_in_transaction(self): waffle.get_waffle_switch_model().objects.create(name='foo', active=True) with transaction.atomic(): with override_switch('foo', active=True): assert waffle.switch_is_active('foo') with override_switch('foo', active=False): assert not waffle.switch_is_active('foo') assert waffle.switch_is_active('foo') class OverrideSwitchTestCase(OverrideSwitchMixin, TestCase): """ Run tests with Django TestCase """ class OverrideSwitchTransactionTestCase(OverrideSwitchMixin, TransactionTestCase): """ Run tests with Django TransactionTestCase """ def req(): r = RequestFactory().get('/') r.user = AnonymousUser() return r class OverrideFlagTestsMixin: def test_flag_existed_and_was_active(self): waffle.get_waffle_flag_model().objects.create(name='foo', everyone=True) with override_flag('foo', active=True): assert waffle.flag_is_active(req(), 'foo') with override_flag('foo', active=False): assert not waffle.flag_is_active(req(), 'foo') assert waffle.get_waffle_flag_model().objects.get(name='foo').everyone def test_flag_existed_and_was_inactive(self): waffle.get_waffle_flag_model().objects.create(name='foo', everyone=False) with override_flag('foo', active=True): assert waffle.flag_is_active(req(), 'foo') with override_flag('foo', active=False): assert not waffle.flag_is_active(req(), 'foo') assert waffle.get_waffle_flag_model().objects.get(name='foo').everyone is False def test_flag_existed_and_was_null(self): waffle.get_waffle_flag_model().objects.create(name='foo', everyone=None) with override_flag('foo', active=True): assert waffle.flag_is_active(req(), 'foo') with override_flag('foo', active=False): assert not waffle.flag_is_active(req(), 'foo') assert waffle.get_waffle_flag_model().objects.get(name='foo').everyone is None def test_flag_did_not_exist(self): assert not waffle.get_waffle_flag_model().objects.filter(name='foo').exists() with override_flag('foo', active=True): assert waffle.flag_is_active(req(), 'foo') with override_flag('foo', active=False): assert not waffle.flag_is_active(req(), 'foo') assert not waffle.get_waffle_flag_model().objects.filter(name='foo').exists() def test_cache_is_flushed_by_testutils_even_in_transaction(self): waffle.get_waffle_flag_model().objects.create(name='foo', everyone=True) with transaction.atomic(): with override_flag('foo', active=True): assert waffle.flag_is_active(req(), 'foo') with override_flag('foo', active=False): assert not waffle.flag_is_active(req(), 'foo') assert waffle.flag_is_active(req(), 'foo') class OverrideFlagsTestCase(OverrideFlagTestsMixin, TestCase): """ Run tests with Django TestCase """ class OverrideFlagsTransactionTestCase(OverrideFlagTestsMixin, TransactionTestCase): """ Run tests with Django TransactionTestCase """ class OverrideSampleTestsMixin: def test_sample_existed_and_was_100(self): waffle.get_waffle_sample_model().objects.create(name='foo', percent='100.0') with override_sample('foo', active=True): assert waffle.sample_is_active('foo') with override_sample('foo', active=False): assert not waffle.sample_is_active('foo') self.assertEqual(Decimal('100.0'), waffle.get_waffle_sample_model().objects.get(name='foo').percent) def test_sample_existed_and_was_0(self): waffle.get_waffle_sample_model().objects.create(name='foo', percent='0.0') with override_sample('foo', active=True): assert waffle.sample_is_active('foo') with override_sample('foo', active=False): assert not waffle.sample_is_active('foo') self.assertEqual(Decimal('0.0'), waffle.get_waffle_sample_model().objects.get(name='foo').percent) def test_sample_existed_and_was_50(self): waffle.get_waffle_sample_model().objects.create(name='foo', percent='50.0') with override_sample('foo', active=True): assert waffle.sample_is_active('foo') with override_sample('foo', active=False): assert not waffle.sample_is_active('foo') self.assertEqual(Decimal('50.0'), waffle.get_waffle_sample_model().objects.get(name='foo').percent) def test_sample_did_not_exist(self): assert not waffle.get_waffle_sample_model().objects.filter(name='foo').exists() with override_sample('foo', active=True): assert waffle.sample_is_active('foo') with override_sample('foo', active=False): assert not waffle.sample_is_active('foo') assert not waffle.get_waffle_sample_model().objects.filter(name='foo').exists() def test_cache_is_flushed_by_testutils_even_in_transaction(self): waffle.get_waffle_sample_model().objects.create(name='foo', percent='100.0') with transaction.atomic(): with override_sample('foo', active=True): assert waffle.sample_is_active('foo') with override_sample('foo', active=False): assert not waffle.sample_is_active('foo') assert waffle.sample_is_active('foo') class OverrideSampleTestCase(OverrideSampleTestsMixin, TestCase): """ Run tests with Django TestCase """ class OverrideSampleTransactionTestCase(OverrideSampleTestsMixin, TransactionTestCase): """ Run tests with Django TransactionTestCase """ class OverrideSwitchOnClassTestsMixin: @classmethod def setUpClass(cls): super().setUpClass() assert not waffle.get_waffle_switch_model().objects.filter(name='foo').exists() waffle.get_waffle_switch_model().objects.create(name='foo', active=True) def test_undecorated_method_is_set_properly_for_switch(self): self.assertFalse(waffle.switch_is_active('foo')) @override_switch('foo', active=False) class OverrideSwitchOnClassTestCase(OverrideSwitchOnClassTestsMixin, TestCase): """ Run tests with Django TestCase """ @override_switch('foo', active=False) class OverrideSwitchOnClassTransactionTestCase(OverrideSwitchOnClassTestsMixin, TransactionTestCase): """ Run tests with Django TransactionTestCase """ class OverrideFlagOnClassTestsMixin: @classmethod def setUpClass(cls): super().setUpClass() assert not waffle.get_waffle_flag_model().objects.filter(name='foo').exists() waffle.get_waffle_flag_model().objects.create(name='foo', everyone=True) def test_undecorated_method_is_set_properly_for_flag(self): self.assertFalse(waffle.flag_is_active(req(), 'foo')) @override_flag('foo', active=False) class OverrideFlagOnClassTestCase(OverrideFlagOnClassTestsMixin, TestCase): """ Run tests with Django TestCase """ @override_flag('foo', active=False) class OverrideFlagOnClassTransactionTestCase(OverrideFlagOnClassTestsMixin, TransactionTestCase): """ Run tests with Django TransactionTestCase """ class OverrideSampleOnClassTestsMixin: @classmethod def setUpClass(cls): super().setUpClass() assert not waffle.get_waffle_sample_model().objects.filter(name='foo').exists() waffle.get_waffle_sample_model().objects.create(name='foo', percent='100.0') def test_undecorated_method_is_set_properly_for_sample(self): self.assertFalse(waffle.sample_is_active('foo')) @override_sample('foo', active=False) class OverrideSampleOnClassTestCase(OverrideSampleOnClassTestsMixin, TestCase): """ Run tests with Django TestCase """ @override_sample('foo', active=False) class OverrideSampleOnClassTransactionTestCase(OverrideSampleOnClassTestsMixin, TransactionTestCase): """ Run tests with Django TransactionTestCase """ class InheritanceOverrideSwitchOnClassTests(OverrideSwitchOnClassTestCase): """ Extend ``OverrideSwitchOnClassTestCase`` and make sure ``override_switch`` change still works. """ def test_child_undecorated_method_is_set_properly_for_switch(self): self.assertFalse(waffle.switch_is_active('foo')) class InheritanceOverrideFlagOnClassTests(OverrideFlagOnClassTestCase): """ Extend ``OverrideFlagOnClassTestCase`` and make sure ``override_flag`` change still works. """ def test_child_undecorated_method_is_set_properly_for_flag(self): self.assertFalse(waffle.flag_is_active(req(), 'foo')) class InheritanceOverrideSampleOnClassTests(OverrideSampleOnClassTestCase): """ Extend ``OverrideSampleOnClassTestCase`` and make sure ``override_sample`` change still works. """ def test_child_undecorated_method_is_set_properly_for_sample(self): self.assertFalse(waffle.sample_is_active('foo')) django-waffle-4.2.0/waffle/tests/test_utils.py000066400000000000000000000012271471570242400214100ustar00rootroot00000000000000from django.conf import settings from django.test import TestCase from django.test.utils import override_settings from waffle import defaults from waffle.utils import get_setting class GetSettingTests(TestCase): def test_overridden_setting(self): prefix = get_setting('CACHE_PREFIX') self.assertEqual(settings.WAFFLE_CACHE_PREFIX, prefix) def test_default_setting(self): age = get_setting('MAX_AGE') self.assertEqual(defaults.MAX_AGE, age) def test_override_settings(self): assert not get_setting('OVERRIDE') with override_settings(WAFFLE_OVERRIDE=True): assert get_setting('OVERRIDE') django-waffle-4.2.0/waffle/tests/test_views.py000066400000000000000000000104051471570242400214030ustar00rootroot00000000000000from django.urls import reverse from waffle import ( get_waffle_flag_model, get_waffle_sample_model, get_waffle_switch_model, ) from waffle.tests.base import TestCase class WaffleViewTests(TestCase): def test_wafflejs(self): response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) self.assertEqual('application/x-javascript', response['content-type']) cache_control = [control.strip() for control in response['cache-control'].split(',')] self.assertIn('max-age=0', cache_control) def test_waffle_status(self): response = self.client.get(reverse('waffle_status')) self.assertEqual(200, response.status_code) self.assertEqual('application/json', response['content-type']) cache_control = [control.strip() for control in response['cache-control'].split(',')] self.assertIn('max-age=0', cache_control) def test_waffle_status_response(self): get_waffle_flag_model().objects.create(name='test_flag_active', everyone=True) get_waffle_flag_model().objects.create(name='test_flag_inactive', everyone=False) get_waffle_switch_model().objects.create(name='test_switch_active', active=True) get_waffle_switch_model().objects.create(name='test_switch_inactive', active=False) get_waffle_sample_model().objects.create(name='test_sample_active', percent=100) get_waffle_sample_model().objects.create(name='test_sample_inactive', percent=0) response = self.client.get(reverse('waffle_status')) self.assertEqual(200, response.status_code) content = response.json() assert 'test_flag_active' in content['flags'].keys() assert content['flags']['test_flag_active']['is_active'] assert 'test_flag_inactive' in content['flags'].keys() assert not content['flags']['test_flag_inactive']['is_active'] assert 'test_switch_active' in content['switches'].keys() assert content['switches']['test_switch_active']['is_active'] assert 'test_switch_inactive' in content['switches'].keys() assert not content['switches']['test_switch_inactive']['is_active'] assert 'test_sample_active' in content['samples'].keys() assert content['samples']['test_sample_active']['is_active'] assert 'test_sample_inactive' in content['samples'].keys() assert not content['samples']['test_sample_inactive']['is_active'] def test_flush_all_flags(self): """Test the 'FLAGS_ALL' list gets invalidated correctly.""" get_waffle_flag_model().objects.create(name='myflag1', everyone=True) response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) assert ('myflag1', True) in response.context['flags'] get_waffle_flag_model().objects.create(name='myflag2', everyone=True) response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) assert ('myflag2', True) in response.context['flags'] def test_flush_all_switches(self): """Test the 'SWITCHES_ALL' list gets invalidated correctly.""" switch = get_waffle_switch_model().objects.create(name='myswitch', active=True) response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) assert ('myswitch', True) in response.context['switches'] switch.active = False switch.save() response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) assert ('myswitch', False) in response.context['switches'] def test_flush_all_samples(self): """Test the 'SAMPLES_ALL' list gets invalidated correctly.""" get_waffle_sample_model().objects.create(name='sample1', percent='100.0') response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) assert ('sample1', True) in response.context['samples'] get_waffle_sample_model().objects.create(name='sample2', percent='100.0') response = self.client.get(reverse('wafflejs')) self.assertEqual(200, response.status_code) assert ('sample2', True) in response.context['samples'] django-waffle-4.2.0/waffle/tests/test_waffle.py000066400000000000000000000772101471570242400215210ustar00rootroot00000000000000import logging import random import threading import unittest from django.contrib.auth import get_user_model from django.conf import settings from django.contrib.auth.models import AnonymousUser, Group from django.db import connection, transaction from django.test import RequestFactory, TransactionTestCase from django.test.utils import override_settings from unittest import mock import waffle from test_app import views from test_app.models import CompanyAwareFlag, CustomSample, CustomSwitch, Company from waffle.middleware import WaffleMiddleware from waffle.tests.base import TestCase DATABASES = {'default', 'readonly'} def get(**kw): request = RequestFactory().get('/foo', data=kw) request.user = AnonymousUser() return request def get_response(request): return 'hello' def process_request(request, view): response = view(request) return WaffleMiddleware(get_response).process_response(request, response) class WaffleTests(TestCase): databases = DATABASES def assert_flag_dynamically_created_with_value(self, expected_value): FLAG_NAME = 'my_dynamically_created_flag' flag_model = waffle.get_waffle_flag_model() assert flag_model.objects.count() == 0 assert expected_value == waffle.flag_is_active(get(), FLAG_NAME) assert flag_model.objects.count() == 1 flag = flag_model.objects.get(name=FLAG_NAME) assert flag.name == FLAG_NAME # We assert no queries are made to ensure flags created when the # `CREATE_MISSING_FLAGS` setting is active are properly cached. with self.assertNumQueries(0): assert expected_value == waffle.flag_is_active(get(), FLAG_NAME) def test_persist_active_flag(self): waffle.get_waffle_flag_model().objects.create(name='myflag', percent='0.1') request = get() # Flag stays on. request.COOKIES['dwf_myflag'] = 'True' response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' in response.cookies self.assertEqual('True', response.cookies['dwf_myflag'].value) def test_persist_inactive_flag(self): waffle.get_waffle_flag_model().objects.create(name='myflag', percent='99.9') request = get() # Flag stays off. request.COOKIES['dwf_myflag'] = 'False' response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' in response.cookies self.assertEqual('False', response.cookies['dwf_myflag'].value) def test_no_set_unused_flag(self): """An unused flag shouldn't have its cookie reset.""" request = get() request.COOKIES['dwf_unused'] = 'True' response = process_request(request, views.flag_in_view) assert 'dwf_unused' not in response.cookies def test_superuser(self): """Test the superuser switch.""" waffle.get_waffle_flag_model().objects.create(name='myflag', superusers=True) request = get() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies superuser = get_user_model()(username='foo', is_superuser=True) request.user = superuser response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies non_superuser = get_user_model()(username='bar', is_superuser=False) non_superuser.save() request.user = non_superuser response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies def test_staff(self): """Test the staff switch.""" waffle.get_waffle_flag_model().objects.create(name='myflag', staff=True) request = get() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies staff = get_user_model()(username='foo', is_staff=True) request.user = staff response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies non_staff = get_user_model()(username='foo', is_staff=False) non_staff.save() request.user = non_staff response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies def test_languages(self): waffle.get_waffle_flag_model().objects.create(name='myflag', languages='en,fr') request = get() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) request.LANGUAGE_CODE = 'en' response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) request.LANGUAGE_CODE = 'de' response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) def test_user(self): """Test the per-user switch.""" user = get_user_model().objects.create(username='foo') flag = waffle.get_waffle_flag_model().objects.create(name='myflag') flag.users.add(user) request = get() request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model().objects.create(username='someone_else') response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies # Unsetting the flag on a user should have an effect. flag.users.remove(user) request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) def test_remove_from_user(self): """Same operation of `test_user` but performed with reverse relation""" user = get_user_model().objects.create(username='foo') flag = waffle.get_waffle_flag_model().objects.create(name='myflag') flag.users.add(user) request = get() request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model().objects.create(username='someone_else') response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies # Unsetting the flag on a user should have an effect. user.flag_set.remove(flag) request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) def test_group(self): """Test the per-group switch.""" group = Group.objects.create(name='foo') user = get_user_model().objects.create(username='bar') user.groups.add(group) flag = waffle.get_waffle_flag_model().objects.create(name='myflag') flag.groups.add(group) request = get() request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model()(username='someone_else') request.user.save() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies # Unsetting the flag on a group should have an effect. flag.groups.remove(group) request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) def test_remove_from_group(self): """Same operation of `test_group` but performed with reverse relation""" group = Group.objects.create(name='foo') user = get_user_model().objects.create(username='bar') user.groups.add(group) flag = waffle.get_waffle_flag_model().objects.create(name='myflag') flag.groups.add(group) request = get() request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model()(username='someone_else') request.user.save() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies # Unsetting the flag on a group should have an effect. group.flag_set.remove(flag) request.user = user response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) def test_authenticated(self): """Test the authenticated/anonymous switch.""" waffle.get_waffle_flag_model().objects.create(name='myflag', authenticated=True) request = get() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model()(username='foo') assert request.user.is_authenticated response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies def test_everyone_on(self): """Test the 'everyone' switch on.""" waffle.get_waffle_flag_model().objects.create(name='myflag', everyone=True) request = get() request.COOKIES['dwf_myflag'] = 'False' response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model()(username='foo') assert request.user.is_authenticated response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies def test_everyone_off(self): """Test the 'everyone' switch off.""" waffle.get_waffle_flag_model().objects.create( name="myflag", everyone=False, authenticated=True ) request = get() request.COOKIES['dwf_myflag'] = 'True' response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies request.user = get_user_model()(username='foo') assert request.user.is_authenticated response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies def test_percent(self): """If you have no cookie, you get a cookie!""" waffle.get_waffle_flag_model().objects.create(name='myflag', percent='50.0') request = get() response = process_request(request, views.flag_in_view) assert 'dwf_myflag' in response.cookies @mock.patch.object(random, 'uniform') def test_reroll(self, uniform): """Even without a cookie, calling flag_is_active twice should return the same value.""" waffle.get_waffle_flag_model().objects.create(name='myflag', percent='50.0') # Make sure we're not really random. request = get() # Create a clean request. assert not hasattr(request, 'waffles') uniform.return_value = '10' # < 50. Flag is True. assert waffle.flag_is_active(request, 'myflag') assert hasattr(request, 'waffles') # We should record this flag. assert 'myflag' in request.waffles assert request.waffles['myflag'][0] uniform.return_value = '70' # > 50. Normally, Flag would be False. assert waffle.flag_is_active(request, 'myflag') assert request.waffles['myflag'][0] def test_undefined(self): """Undefined flags are always false.""" request = get() assert not waffle.flag_is_active(request, 'foo') @override_settings(WAFFLE_FLAG_DEFAULT=True) def test_undefined_default(self): """WAFFLE_FLAG_DEFAULT controls undefined flags.""" request = get() assert waffle.flag_is_active(request, 'foo') @override_settings(WAFFLE_OVERRIDE=True) def test_override(self): request = get(foo='1') waffle.get_waffle_flag_model().objects.create(name='foo') # Off for everyone. assert waffle.flag_is_active(request, 'foo') def test_testing_flag(self): waffle.get_waffle_flag_model().objects.create(name='foo', testing=True) request = get(dwft_foo='1') assert waffle.flag_is_active(request, 'foo') assert 'foo' in request.waffle_tests assert request.waffle_tests['foo'] # GET param should override cookie request = get(dwft_foo='0') request.COOKIES['dwft_foo'] = 'True' assert not waffle.flag_is_active(request, 'foo') assert 'foo' in request.waffle_tests assert not request.waffle_tests['foo'] def test_testing_disabled_flag(self): waffle.get_waffle_flag_model().objects.create(name='foo') request = get(dwft_foo='1') assert not waffle.flag_is_active(request, 'foo') assert not hasattr(request, 'waffle_tests') request = get(dwft_foo='0') assert not waffle.flag_is_active(request, 'foo') assert not hasattr(request, 'waffle_tests') def test_testing_flag_header(self): waffle.get_waffle_flag_model().objects.create(name='foo', testing=True) request = RequestFactory().get('/foo', HTTP_DWFT_FOO='1') request.user = AnonymousUser() assert waffle.flag_is_active(request, 'foo') assert 'foo' in request.waffle_tests assert request.waffle_tests['foo'] # header should override cookie request = RequestFactory().get('/foo', HTTP_DWFT_FOO='0') request.user = AnonymousUser() request.COOKIES['dwft_foo'] = 'True' assert not waffle.flag_is_active(request, 'foo') assert 'foo' in request.waffle_tests assert not request.waffle_tests['foo'] def test_set_then_unset_testing_flag(self): waffle.get_waffle_flag_model().objects.create(name='myflag', testing=True) response = self.client.get('/flag_in_view?dwft_myflag=1') self.assertEqual(b'on', response.content) response = self.client.get('/flag_in_view') self.assertEqual(b'on', response.content) response = self.client.get('/flag_in_view?dwft_myflag=0') self.assertEqual(b'off', response.content) response = self.client.get('/flag_in_view') self.assertEqual(b'off', response.content) response = self.client.get('/flag_in_view?dwft_myflag=1') self.assertEqual(b'on', response.content) @override_settings(DATABASE_ROUTERS=['waffle.tests.base.ReplicationRouter']) def test_everyone_on_read_from_write_db(self): flag = waffle.get_waffle_flag_model().objects.create(name='myflag', everyone=True) request = get() response = process_request(request, views.flag_in_view) # By default, flag_is_active should hit whatever it configured as the # read DB (so values will be stale if replication is lagged). self.assertEqual(b'off', response.content) with override_settings(WAFFLE_READ_FROM_WRITE_DB=True): # Save the flag again to flush the cache. flag.save() # The next read should now be directed to the write DB, ensuring # the cache and DB are in sync. response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) @override_settings( WAFFLE_FLAG_MODEL="test_app.CompanyAwareFlag", AUTH_USER_MODEL="test_app.CompanyUser", ) def test_pluggable_flag_model(self): flag_model = waffle.get_waffle_flag_model() self.assertEqual(CompanyAwareFlag, flag_model) acme_company = Company.objects.create(name='Acme Ltd.') feline_company = Company.objects.create(name='Feline LLC') acme_company_flag = waffle.get_waffle_flag_model().objects.create( name="myflag", superusers=True ) acme_company_flag.companies.add(acme_company) request = get() response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies acme_user = get_user_model()(username='acme.mcfield', company=acme_company) request.user = acme_user response = process_request(request, views.flag_in_view) self.assertEqual(b'on', response.content) assert 'dwf_myflag' not in response.cookies feline_user = get_user_model()(username='acme.mcfield', company=feline_company) request.user = feline_user response = process_request(request, views.flag_in_view) self.assertEqual(b'off', response.content) assert 'dwf_myflag' not in response.cookies @override_settings(WAFFLE_CREATE_MISSING_FLAGS=True) @override_settings(WAFFLE_FLAG_DEFAULT=False) def test_flag_created_dynamically_default_false(self): self.assert_flag_dynamically_created_with_value(False) @override_settings(WAFFLE_CREATE_MISSING_FLAGS=True) @override_settings(WAFFLE_FLAG_DEFAULT=True) def test_flag_created_dynamically_default_true(self): self.assert_flag_dynamically_created_with_value(True) @mock.patch('waffle.models.logger') def test_no_logging_missing_flag_by_default(self, mock_logger): request = get() waffle.flag_is_active(request, 'foo') mock_logger.log.call_count == 0 @override_settings(WAFFLE_LOG_MISSING_FLAGS=logging.WARNING) @mock.patch('waffle.models.logger') def test_logging_missing_flag(self, mock_logger): request = get() waffle.flag_is_active(request, 'foo') mock_logger.log.assert_called_with(logging.WARNING, 'Flag %s not found', 'foo') class SwitchTests(TestCase): databases = DATABASES def assert_switch_dynamically_created_with_value(self, expected_value): SWITCH_NAME = 'my_dynamically_created_switch' assert waffle.get_waffle_switch_model().objects.count() == 0 assert expected_value == waffle.switch_is_active(SWITCH_NAME) assert waffle.get_waffle_switch_model().objects.count() == 1 switch = waffle.get_waffle_switch_model().objects.get(name=SWITCH_NAME) assert switch.name == SWITCH_NAME assert expected_value == switch.active # We assert no queries are made to ensure switches created when the # `CREATE_MISSING_SWITCHES` setting is active are properly cached. with self.assertNumQueries(0): assert expected_value == waffle.switch_is_active(SWITCH_NAME) def test_switch_active(self): switch = waffle.get_waffle_switch_model().objects.create( name="myswitch", active=True ) assert waffle.switch_is_active(switch.name) def test_switch_inactive(self): switch = waffle.get_waffle_switch_model().objects.create( name="myswitch", active=False ) assert not waffle.switch_is_active(switch.name) def test_switch_active_from_cache(self): """Do not make two queries for an existing active switch.""" switch = waffle.get_waffle_switch_model().objects.create( name="myswitch", active=True ) # Get the value once so that it will be put into the cache assert waffle.switch_is_active(switch.name) queries = len(connection.queries) assert waffle.switch_is_active(switch.name) self.assertEqual(queries, len(connection.queries)) def test_switch_inactive_from_cache(self): """Do not make two queries for an existing inactive switch.""" switch = waffle.get_waffle_switch_model().objects.create( name="myswitch", active=False ) # Get the value once so that it will be put into the cache assert not waffle.switch_is_active(switch.name) queries = len(connection.queries) assert not waffle.switch_is_active(switch.name) self.assertEqual(queries, len(connection.queries)) def test_undefined(self): assert not waffle.switch_is_active('foo') @override_settings(WAFFLE_SWITCH_DEFAULT=True) def test_undefined_default(self): assert waffle.switch_is_active('foo') @override_settings(DEBUG=True) def test_no_query(self): """Do not make two queries for a non-existent switch.""" assert not waffle.get_waffle_switch_model().objects.filter(name='foo').exists() queries = len(connection.queries) assert not waffle.switch_is_active('foo') assert len(connection.queries) > queries queries = len(connection.queries) assert not waffle.switch_is_active('foo') self.assertEqual(queries, len(connection.queries)) @override_settings(DATABASE_ROUTERS=['waffle.tests.base.ReplicationRouter']) def test_read_from_write_db(self): switch = waffle.get_waffle_switch_model().objects.create( name="switch", active=True ) # By default, switch_is_active should hit whatever it configured as the # read DB (so values will be stale if replication is lagged). assert not waffle.switch_is_active(switch.name) with override_settings(WAFFLE_READ_FROM_WRITE_DB=True): # Save the switch again to flush the cache. switch.save() # The next read should now be directed to the write DB, ensuring # the cache and DB are in sync. assert waffle.switch_is_active(switch.name) @override_settings(WAFFLE_SWITCH_MODEL='test_app.CustomSwitch') def test_pluggable_switch_model(self): switch_model = waffle.get_waffle_model('SWITCH_MODEL') self.assertEqual(CustomSwitch, switch_model) switch_model.objects.create(name='test_switch_off', active=False) switch_model.objects.create(name='test_switch_on', active=True) assert not waffle.switch_is_active('test_switch_off') assert waffle.switch_is_active('test_switch_on') @override_settings(WAFFLE_CREATE_MISSING_SWITCHES=True) @override_settings(WAFFLE_SWITCH_DEFAULT=False) def test_switch_created_dynamically_false(self): self.assert_switch_dynamically_created_with_value(False) @override_settings(WAFFLE_CREATE_MISSING_SWITCHES=True) @override_settings(WAFFLE_SWITCH_DEFAULT=True) def test_switch_created_dynamically_true(self): self.assert_switch_dynamically_created_with_value(True) @mock.patch('waffle.models.logger') def test_no_logging_missing_switch_by_default(self, mock_logger): waffle.switch_is_active('foo') mock_logger.log.call_count == 0 @override_settings(WAFFLE_LOG_MISSING_SWITCHES=logging.WARNING) @mock.patch('waffle.models.logger') def test_logging_missing_switch(self, mock_logger): waffle.switch_is_active("foo") mock_logger.log.assert_called_with( logging.WARNING, "Switch %s not found", "foo" ) class SampleTests(TestCase): databases = DATABASES def assert_sample_dynamically_created_with_value(self, is_active, expected_value): SAMPLE_NAME = 'my_dynamically_created_sample' assert waffle.get_waffle_sample_model().objects.count() == 0 assert is_active == waffle.sample_is_active(SAMPLE_NAME) assert waffle.get_waffle_sample_model().objects.count() == 1 sample = waffle.get_waffle_sample_model().objects.get(name=SAMPLE_NAME) assert sample.name == SAMPLE_NAME assert sample.percent == expected_value # We assert no queries are made to ensure samples created when the # `CREATE_MISSING_SAMPLES` setting is active are properly cached. with self.assertNumQueries(0): assert is_active == waffle.sample_is_active(SAMPLE_NAME) def test_sample_100(self): sample = waffle.get_waffle_sample_model().objects.create( name="sample", percent="100.0" ) assert waffle.sample_is_active(sample.name) def test_sample_0(self): sample = waffle.get_waffle_sample_model().objects.create( name="sample", percent="0.0" ) assert not waffle.sample_is_active(sample.name) def test_undefined(self): assert not waffle.sample_is_active('foo') @override_settings(WAFFLE_SAMPLE_DEFAULT=True) def test_undefined_default(self): assert waffle.sample_is_active('foo') @override_settings(DATABASE_ROUTERS=['waffle.tests.base.ReplicationRouter']) def test_read_from_write_db(self): sample = waffle.get_waffle_sample_model().objects.create( name="sample", percent="100.0" ) # By default, sample_is_active should hit whatever it configured as the # read DB (so values will be stale if replication is lagged). assert not waffle.sample_is_active(sample.name) with override_settings(WAFFLE_READ_FROM_WRITE_DB=True): # Save the sample again to flush the cache. sample.save() # The next read should now be directed to the write DB, ensuring # the cache and DB are in sync. assert waffle.sample_is_active(sample.name) @override_settings(WAFFLE_CREATE_MISSING_SAMPLES=True) @override_settings(WAFFLE_SAMPLE_DEFAULT=False) def test_sample_created_dynamically_default_false(self): self.assert_sample_dynamically_created_with_value(False, 0.0) @override_settings(WAFFLE_CREATE_MISSING_SAMPLES=True) @override_settings(WAFFLE_SAMPLE_DEFAULT=True) def test_sample_created_dynamically_default_true(self): self.assert_sample_dynamically_created_with_value(True, 100.0) @mock.patch('waffle.models.logger') def test_no_logging_missing_sample_by_default(self, mock_logger): waffle.switch_is_active('foo') mock_logger.log.call_count == 0 @override_settings(WAFFLE_LOG_MISSING_SAMPLES=logging.WARNING) @mock.patch('waffle.models.logger') def test_logging_missing_sample(self, mock_logger): waffle.sample_is_active('foo') mock_logger.log.assert_called_with(logging.WARNING, 'Sample %s not found', 'foo') @override_settings(WAFFLE_SAMPLE_MODEL='test_app.CustomSample') def test_pluggable_sample_model(self): sample_model = waffle.get_waffle_model('SAMPLE_MODEL') self.assertEqual(CustomSample, sample_model) sample_model.objects.create(name='test_sample_off', percent=0) sample_model.objects.create(name='test_sample_on', percent=100) assert not waffle.sample_is_active('test_sample_off') assert waffle.sample_is_active('test_sample_on') class TransactionTestMixin: """Mixin providing an abstract test case for writing in a transaction. """ def create_toggle(self): """Create an inactive feature toggle (i.e. flag, switch, sample).""" raise NotImplementedError def flip_toggle(self, toggle): """Flip the toggle to an active state.""" raise NotImplementedError def toggle_is_active(self, toggle): """Use the built-in *_is_active helper to check the toggle's state.""" raise NotImplementedError @unittest.skipIf('sqlite3' in settings.DATABASES['default']['ENGINE'], 'This test uses threads, which the sqlite3 DB engine ' 'does not support.') def test_flip_toggle_in_transaction(self): """Wait to invalidate the cache until after the current transaction. This test covers a potential race condition where, if the cache were flushed in the middle of a transaction, the next read from the database (before the transaction is committed) would get a stale value and cache it. See #296 for more context. """ toggle = self.create_toggle() self.addCleanup(toggle.delete) written_in_background_thread = threading.Event() read_in_main_thread = threading.Event() @transaction.atomic def update_toggle(): self.flip_toggle(toggle) # Signal to the main thread that the toggle has been updated, but # the transaction is not yet committed. written_in_background_thread.set() # Pause here to allow the main thread to make an assertion. read_in_main_thread.wait(timeout=1) # Start a background thread to update the toggle in a transaction. t = threading.Thread(target=update_toggle) t.daemon = True t.start() # After the toggle is updated but before the transaction is committed, # the cache will still have the previous value. written_in_background_thread.wait(timeout=1) assert not self.toggle_is_active(toggle) # After the transaction is committed, the cache should have been # invalidated, hence the next call to *_is_active should have the # correct value. read_in_main_thread.set() t.join(timeout=1) assert self.toggle_is_active(toggle) class FlagTransactionTests(TransactionTestMixin, TransactionTestCase): def create_toggle(self): return waffle.get_waffle_flag_model().objects.create( name='transaction-flag-name', everyone=False ) def flip_toggle(self, flag): flag.everyone = True flag.save() def toggle_is_active(self, flag): return waffle.flag_is_active(get(), flag.name) class SwitchTransactionTests(TransactionTestMixin, TransactionTestCase): def create_toggle(self): return waffle.get_waffle_switch_model().objects.create( name="transaction-switch-name", active=False ) def flip_toggle(self, switch): switch.active = True switch.save() def toggle_is_active(self, switch): return waffle.switch_is_active(switch.name) class SampleTransactionTests(TransactionTestMixin, TransactionTestCase): def create_toggle(self): return waffle.get_waffle_sample_model().objects.create( name="transaction-sample-name", percent=0 ) def flip_toggle(self, sample): sample.percent = 100 sample.save() def toggle_is_active(self, sample): return waffle.sample_is_active(sample.name) class FunctionTests(TestCase): @mock.patch.object(random, 'uniform') def test_percent(self, uniform): """If you have no cookie, you get a cookie!""" uniform.return_value = '10' waffle.get_waffle_flag_model().objects.create(name='myflag', percent='50.0') request = get() response = process_request(request, views.flag_in_view) assert 'dwf_myflag' in response.cookies self.assertEqual('True', response.cookies['dwf_myflag'].value) self.assertEqual(b'on', response.content) @mock.patch.object(random, 'uniform') def test_percent_readonly(self, uniform): uniform.return_value = '10' """If you have no cookie, you do not get a cookie if we just have a question!""" waffle.get_waffle_flag_model().objects.create(name='myflag', percent='50.0') request = get() response = process_request(request, views.flag_in_view_readonly) assert 'dwf_myflag' not in response.cookies self.assertEqual(b'off', response.content) django-waffle-4.2.0/waffle/testutils.py000066400000000000000000000062461471570242400201150ustar00rootroot00000000000000from typing import Generic, Optional, TypeVar, Union from django.test.utils import TestContextDecorator from waffle import ( get_waffle_flag_model, get_waffle_sample_model, get_waffle_switch_model, ) __all__ = ['override_flag', 'override_sample', 'override_switch'] _T = TypeVar("_T") class _overrider(TestContextDecorator, Generic[_T]): def __init__(self, name: str, active: _T): super().__init__() self.name = name self.active = active def get(self) -> None: self.obj, self.created = self.cls.objects.get_or_create(name=self.name) def update(self, active: _T) -> None: raise NotImplementedError def get_value(self) -> _T: raise NotImplementedError def enable(self) -> None: self.get() self.old_value = self.get_value() if self.old_value != self.active: self.update(self.active) def disable(self) -> None: if self.created: self.obj.delete() self.obj.flush() else: self.update(self.old_value) class override_switch(_overrider[bool]): """ override_switch is a contextmanager for easier testing of switches. It accepts two parameters, name of the switch and it's state. Example usage:: with override_switch('happy_mode', active=True): ... If `Switch` already existed, it's value would be changed inside the context block, then restored to the original value. If `Switch` did not exist before entering the context, it is created, then removed at the end of the block. It can also act as a decorator:: @override_switch('happy_mode', active=True) def test_happy_mode_enabled(): ... """ cls = get_waffle_switch_model() def update(self, active: bool) -> None: obj = self.cls.objects.get(pk=self.obj.pk) obj.active = active obj.save() obj.flush() def get_value(self) -> bool: return self.obj.active class override_flag(_overrider[Optional[bool]]): cls = get_waffle_flag_model() def update(self, active: Optional[bool]) -> None: obj = self.cls.objects.get(pk=self.obj.pk) obj.everyone = active obj.save() obj.flush() def get_value(self) -> Optional[bool]: return self.obj.everyone class override_sample(_overrider[Union[bool, float]]): cls = get_waffle_sample_model() def get(self) -> None: try: self.obj = self.cls.objects.get(name=self.name) self.created = False except self.cls.DoesNotExist: self.obj = self.cls.objects.create(name=self.name, percent='0.0') self.created = True def update(self, active: Union[bool, float]) -> None: if active is True: p = 100.0 elif active is False: p = 0.0 else: p = active obj = self.cls.objects.get(pk=self.obj.pk) obj.percent = f'{p}' obj.save() obj.flush() def get_value(self) -> Union[bool, float]: p = self.obj.percent if p == 100.0: return True if p == 0.0: return False return p django-waffle-4.2.0/waffle/urls.py000066400000000000000000000003171471570242400170330ustar00rootroot00000000000000from django.urls import path from waffle.views import wafflejs, waffle_json urlpatterns = [ path('wafflejs', wafflejs, name='wafflejs'), path('waffle_status', waffle_json, name='waffle_status'), ] django-waffle-4.2.0/waffle/utils.py000066400000000000000000000013561471570242400172120ustar00rootroot00000000000000from __future__ import annotations import hashlib from typing import Any from django.conf import settings from django.core.cache import BaseCache, caches import waffle from waffle import defaults def get_setting(name: str, default: Any = None) -> Any: try: return getattr(settings, 'WAFFLE_' + name) except AttributeError: return getattr(defaults, name, default) def keyfmt(k: str, v: str | None = None) -> str: prefix = get_setting('CACHE_PREFIX') + waffle.__version__ if v is None: key = prefix + k else: key = prefix + hashlib.md5((k % v).encode('utf-8')).hexdigest() return key def get_cache() -> BaseCache: CACHE_NAME = get_setting('CACHE_NAME') return caches[CACHE_NAME] django-waffle-4.2.0/waffle/views.py000066400000000000000000000041631471570242400172060ustar00rootroot00000000000000from __future__ import annotations from typing import Any from django.http import HttpRequest, HttpResponse, JsonResponse from django.template import loader from django.views.decorators.cache import never_cache from waffle import get_waffle_flag_model, get_waffle_switch_model, get_waffle_sample_model from waffle.utils import get_setting @never_cache def wafflejs(request): return HttpResponse(_generate_waffle_js(request), content_type='application/x-javascript') def _generate_waffle_js(request: HttpRequest) -> str: flags = get_waffle_flag_model().get_all() flag_values = [(f.name, f.is_active(request)) for f in flags] switches = get_waffle_switch_model().get_all() switch_values = [(s.name, s.is_active()) for s in switches] samples = get_waffle_sample_model().get_all() sample_values = [(s.name, s.is_active()) for s in samples] return loader.render_to_string('waffle/waffle.js', { 'flags': flag_values, 'switches': switch_values, 'samples': sample_values, 'flag_default': get_setting('FLAG_DEFAULT'), 'switch_default': get_setting('SWITCH_DEFAULT'), 'sample_default': get_setting('SAMPLE_DEFAULT'), }) @never_cache def waffle_json(request): return JsonResponse(_generate_waffle_json(request)) def _generate_waffle_json(request: HttpRequest) -> dict[str, dict[str, Any]]: flags = get_waffle_flag_model().get_all() flag_values = { f.name: { 'is_active': f.is_active(request), 'last_modified': f.modified, } for f in flags } switches = get_waffle_switch_model().get_all() switch_values = { s.name: { 'is_active': s.is_active(), 'last_modified': s.modified, } for s in switches } samples = get_waffle_sample_model().get_all() sample_values = { s.name: { 'is_active': s.is_active(), 'last_modified': s.modified, } for s in samples } return { 'flags': flag_values, 'switches': switch_values, 'samples': sample_values, }