Skip to content

Commit

Permalink
prepare 7.4.0 release (#164)
Browse files Browse the repository at this point in the history
  • Loading branch information
LaunchDarklyReleaseBot authored Feb 16, 2022
1 parent 5f9b0b7 commit ea9e1f4
Show file tree
Hide file tree
Showing 10 changed files with 957 additions and 12 deletions.
3 changes: 1 addition & 2 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,7 @@ jobs:
name: verify typehints
command: |
export PATH="/home/circleci/.local/bin:$PATH"
mypy --install-types --non-interactive ldclient testing
mypy --config-file mypy.ini ldclient testing
make lint
- unless:
condition: <<parameters.skip-sse-contract-tests>>
Expand Down
60 changes: 53 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,18 +32,64 @@ The additional requirements files `consul-requirements.txt`, `dynamodb-requireme

### Testing

To run all unit tests:
To run all unit tests except for the database integrations:

```shell
make test
```
pytest
```

By default, the full unit test suite includes live tests of the integrations for Consul, DynamoDB, and Redis. Those tests expect you to have instances of all of those databases running locally. To skip them, set the environment variable `LD_SKIP_DATABASE_TESTS=1` before running the tests.
To run all unit tests including the database integrations (this requires you to have instances of Consul, DynamoDB, and Redis running locally):

```shell
make test-all
```

There are also integration tests that can be run against the LaunchDarkly service. To enable them, set the environment variable `LD_SDK_KEY` to a valid production SDK Key.

### Portability
It is preferable to run tests against all supported minor versions of Python (as described in `README.md` under Requirements), or at least the lowest and highest versions, prior to submitting a pull request. However, LaunchDarkly's CI tests will run automatically against all supported versions.

Most portability issues are addressed by using the `six` package. We are avoiding the use of `__future__` imports, since they can easily be omitted by mistake causing code in one file to behave differently from another; instead, whenever possible, use an explicit approach that makes it clear what the desired behavior is in all Python versions (e.g. if you want to do floor division, use `//`; if you want to divide as floats, explicitly cast to floats).
### Building documentation

It is preferable to run tests against all supported minor versions of Python (as described in `README.md` under Requirements), or at least the lowest and highest versions, prior to submitting a pull request. However, LaunchDarkly's CI tests will run automatically against all supported versions.
See "Documenting types and methods" below. To build the documentation locally, so you can see the effects of any changes before a release:

```shell
make docs
```

The output will appear in `docs/build/html`. Its formatting will be somewhat different since it does not have the same stylesheets used on readthedocs.io.

### Running the linter

The `mypy` tool is used in CI to verify type hints and warn of potential code problems. To run it locally:

```shell
make lint
```

## Code organization

The SDK's module structure is as follows:

* `ldclient`: This module exports the most commonly used classes and methods in the SDK, such as `LDClient`. The implementations may live in other modules, but applications should not need to import a more specific module such as `ldclient.client` to get those symbols.
* `ldclient.integrations`: This module contains entry points for optional features that are related to how the SDK communicates with other systems, such as `Redis`.
* `ldclient.interfaces`: This namespace contains types that do not do anything by themselves, but may need to be referenced if you are using optional features or implementing a custom component.

A special case is the module `ldclient.impl`, and any modules within it. Everything under `impl` is considered a private implementation detail: all files there are excluded from the generated documentation, and are considered subject to change at any time and not supported for direct use by application developers. Alternately, class names can be prefixed with an underscore to be "private by convention"; that will at least prevent them from being included in wildcard imports like `from ldclient import *`, but it is still preferable to avoid a proliferation of implementation-only modules within the main `ldclient` module, since developers may wrongly decide to reference such modules in imports.

So, if there is a class whose existence is entirely an implementation detail, it should be in `impl`. Similarly, classes that are _not_ in `impl` must not expose any public members (i.e. symbols that do not have an underscore prefix) that are not meant to be part of the supported public API. This is important because of our guarantee of backward compatibility for all public APIs within a major version: we want to be able to change our implementation details to suit the needs of the code, without worrying about breaking a customer's code. Due to how the language works, we can't actually prevent an application developer from referencing those classes in their code, but this convention makes it clear that such use is discouraged and unsupported.

### Type hints

Python does not require the use of type hints, but they can be extremely helpful for spotting mistakes and for improving the IDE experience, so we should always use them in the SDK. Every method in the public API is expected to have type hints for all non-`self` parameters, and for its return value if any.

It's also desirable to use type hints for private attributes, to catch possible mistakes in their use. Until all versions of Python that we support allow the PEP 526 syntax for doing this, we must do it via a comment in the format that `mypy` understands, for instance:

```python
self._some_attribute = None # type: Optional[int]
```

## Documenting types and methods

All classes and public methods outside of `ldclient.impl` should have docstrings in Sphinx format. These are used to build the documentation that is published on [readthedocs.io](https://launchdarkly-python-sdk.readthedocs.io/). See the [Sphinx documentation](https://www.sphinx-doc.org/en/master/) for details of the docstring format.

Please try to make the style and terminology in documentation comments consistent with other documentation comments in the SDK. Also, if a class or method is being added that has an equivalent in other SDKs, and if we have described it in a consistent away in those other SDKs, please reuse the text whenever possible (with adjustments for anything language-specific) rather than writing new text.
18 changes: 18 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,3 +1,21 @@

PYTEST_FLAGS=-W error::SyntaxWarning

test:
LD_SKIP_DATABASE_TESTS=1 pytest $(PYTEST_FLAGS)

test-all:
pytest $(PYTEST_FLAGS)

lint:
mypy --install-types --non-interactive --config-file mypy.ini ldclient testing

docs:
cd docs && make html

.PHONY: test test-all lint docs


TEMP_TEST_OUTPUT=/tmp/contract-test-service.log

# port 8000 and 9000 is already used in the CI environment because we're
Expand Down
12 changes: 12 additions & 0 deletions docs/api-testing.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
Test fixtures
=============

ldclient.integrations.test_data module
--------------------------------------

The entry point for this feature is :class:`ldclient.integrations.test_data.TestData`.

.. automodule:: ldclient.integrations.test_data
:members:
:special-members: __init__
:show-inheritance:
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,5 @@ For more information, see LaunchDarkly's `Quickstart <https://docs.launchdarkly.
api-main
api-integrations
api-extending
api-testing
api-deprecated
Empty file.
22 changes: 22 additions & 0 deletions ldclient/impl/integrations/test_data/test_data_source.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import copy
from ldclient.versioned_data_kind import FEATURES
from ldclient.rwlock import ReadWriteLock


class _TestDataSource():

def __init__(self, feature_store, test_data):
self._feature_store = feature_store
self._test_data = test_data

def start(self):
self._feature_store.init(self._test_data._make_init_data())

def stop(self):
self._test_data._closed_instance(self)

def initialized(self):
return True

def upsert(self, new_flag):
self._feature_store.upsert(FEATURES, new_flag)
Original file line number Diff line number Diff line change
Expand Up @@ -206,9 +206,9 @@ class Files:
"""

@staticmethod
def new_data_source(paths: List[str],
auto_update: bool=False,
poll_interval: float=1,
def new_data_source(paths: List[str],
auto_update: bool=False,
poll_interval: float=1,
force_polling: bool=False) -> object:
"""Provides a way to use local files as a source of feature flag state. This would typically be
used in a test environment, to operate using a predetermined feature flag state without an
Expand Down
Loading

0 comments on commit ea9e1f4

Please sign in to comment.