diff --git a/.gitignore b/.gitignore index c32acd6..7b0a7e3 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,6 @@ __pycache__ *.eggs *.egg-info dist -build eggs parts bin @@ -34,5 +33,6 @@ node_modules # Local dev Dockerfile docker-compose.yml +.DS_Store tests/migrations/* diff --git a/MANIFEST.in b/MANIFEST.in index bb19260..7e575cd 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,4 @@ include *.md include requirements.txt +include requirements/common.txt +include requirements/development.txt diff --git a/django_sharding/__init__.py b/django_sharding/__init__.py index dfb07e8..5bb6fc0 100644 --- a/django_sharding/__init__.py +++ b/django_sharding/__init__.py @@ -1,3 +1,4 @@ -__version__ = '0.0.1' +# This file must remain constants only for the version to be importable in setup.py +VERSION = '1.0.0' default_app_config = 'django_sharding.apps.ShardingConfig' diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f0d6475 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = DjangoSharding +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/_build_html/.buildinfo b/docs/_build_html/.buildinfo new file mode 100644 index 0000000..8a659c4 --- /dev/null +++ b/docs/_build_html/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 5f19a570fbef63952f26e26f6f9cf303 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/_build_html/.doctrees/components/IDGeneration.doctree b/docs/_build_html/.doctrees/components/IDGeneration.doctree new file mode 100644 index 0000000..5f74bcc Binary files /dev/null and b/docs/_build_html/.doctrees/components/IDGeneration.doctree differ diff --git a/docs/_build_html/.doctrees/components/IDGeneration0.doctree b/docs/_build_html/.doctrees/components/IDGeneration0.doctree new file mode 100644 index 0000000..6fbc3f3 Binary files /dev/null and b/docs/_build_html/.doctrees/components/IDGeneration0.doctree differ diff --git a/docs/_build_html/.doctrees/components/OtherComponents.doctree b/docs/_build_html/.doctrees/components/OtherComponents.doctree new file mode 100644 index 0000000..c320a90 Binary files /dev/null and b/docs/_build_html/.doctrees/components/OtherComponents.doctree differ diff --git a/docs/_build_html/.doctrees/components/ReadStrategies.doctree b/docs/_build_html/.doctrees/components/ReadStrategies.doctree new file mode 100644 index 0000000..7ca7e26 Binary files /dev/null and b/docs/_build_html/.doctrees/components/ReadStrategies.doctree differ diff --git a/docs/_build_html/.doctrees/components/Router.doctree b/docs/_build_html/.doctrees/components/Router.doctree new file mode 100644 index 0000000..b341e08 Binary files /dev/null and b/docs/_build_html/.doctrees/components/Router.doctree differ diff --git a/docs/_build_html/.doctrees/components/ShardingFunctions.doctree b/docs/_build_html/.doctrees/components/ShardingFunctions.doctree new file mode 100644 index 0000000..55ccaa1 Binary files /dev/null and b/docs/_build_html/.doctrees/components/ShardingFunctions.doctree differ diff --git a/docs/_build_html/.doctrees/environment.pickle b/docs/_build_html/.doctrees/environment.pickle new file mode 100644 index 0000000..30a5fb4 Binary files /dev/null and b/docs/_build_html/.doctrees/environment.pickle differ diff --git a/docs/_build_html/.doctrees/index.doctree b/docs/_build_html/.doctrees/index.doctree new file mode 100644 index 0000000..393d204 Binary files /dev/null and b/docs/_build_html/.doctrees/index.doctree differ diff --git a/docs/_build_html/_sources/components/IDGeneration.rst.txt b/docs/_build_html/_sources/components/IDGeneration.rst.txt new file mode 100644 index 0000000..9ad5cee --- /dev/null +++ b/docs/_build_html/_sources/components/IDGeneration.rst.txt @@ -0,0 +1,141 @@ +.. ID Generation: + +================ +ID Generation +================ + +When sharding your data there are a few important upfront decisions to make, one +of the most important ones is how identify each of your models. There are several +common strategies and this library allows you to configure this yourself if you +know the strategy you'd like to use. + +The reason this becomes important is that once you pick a strategy, those ids +will be used in your foreign keys and it will be difficult to change. There +are a few common strategies, most of which come shipped with the package. + +1) Unique shard IDs generated using the time +-------------------------------------------- + +This strategy uses a 64 bit integer to encode the time the item was created, the +shard it was created on and a counter. It works by creating a counter on each of +the shards. It allows you to store as many unique combinations of time, +shard and counter as can fit in that 64 bit integer, which is 1000 per shard per +millisecond. + +i.e. the integer 3863625104385 + +:: + + from datetime import datetime + + id = 3863625104385 + + date_created = datetime.fromtimestamp(((id >> 23) + 1476914064192)/ 1000) + # datetime.datetime(2016, 10, 19, 18, 2, 4, 772000) + + counter = int(bin(id)[-10:], 2) + # 1st object created + + shard = int(bin(id)[-23:-10], 2) + # 31st shard + + +This method supports up to 8192 shards (13 bits) and up to 1024 inserts per +millisecond (10 bits). this should be more than enough for most use cases as +it has been used in places like Instagram where scale is an issue. + + +Note: While I have only included the Postgres implimentation of this so far, it is not +difficult to adapt this for other databases (PRs welcome!). + + +2) Use a UUID & shard id combination +------------------------------------ + +This is a much simpler route and has the benefit of being easier to understand +as each of the ids is just a concatenation or a uuid and a shard's id. The +downside to this approach is that if you ever needed to move a record from one +database to another, there can be uuid collisions (even if those are fairly +unlikely). + + +3) Use a simple integer +----------------------- + +Instead of generating more complicated IDs, if we use a counter or sequence on +the main database to generate the IDs then we can use an integer to have unique +IDs across all the shards as the counter's increment is atomic and thus we have +no issues with collisions. Note: I have not included this implementation in the +package yet. + +The included implementation of this uses a table on the main database rather +than a counter to proxy the auto incrementing field's counter. This was included +as this package was created in part to replace an existing system that worked +this way. + + +Writing Your Own +---------------- + +When writing your own, you must provide a class with a `get_next_id` method on +it. There are no other specific requirements, as you can also implement the +caller and provide any args needed. + +:: + + class BaseIDGenerationStrategy(object): + """ + A strategy for Generating unique identifiers. + """ + def get_next_id(self, database=None): + """ + A function which returns a new unique identifier. + """ + raise NotImplemented + + +Pinterest +--------- + +They recently wrote a `lovely article `_ +about their sharding strategy. They use a 64 bit ID that works like so: + + +:: + + def create_item_id(self, database, model_class, local_id): + return ( + (self.database_name_to_id_map[database] << 46) | + (self.model_to_id_map[model_class] << 36) | + (local_id <<0) + ) + + def get_info_from_item_id(self, item_id): + database_id = (item_id >> 46) & 0xFFFF + model_id = (item_id >> 36) & 0x3FF + local_id = (item_id >> 0) & 0xFFFFFFFFF + return ( + self.database_id_to_name_map[database_id], + model_id_to_class_map[model_id], + local_id + ) + +By using the above method to reference items, you need not choose an explicit ID +generation method and instead the `local_id` can simply by an autoincrementing +field on that table. + +That field would look something like this: + +:: + + class ShardedLocalIDField(ShardedIDFieldMixin, AutoField): + def __init__(self, *args, **kwargs): + kwargs['strategy'] = None + return super(ShardedLocalIDField, self).__init__(*args, **kwargs) + + def get_pk_value_on_save(self, instance): + return super(AutoField, self).get_pk_value_on_save(instance) + + +While I have not included all of the code required to use this type of sharding +strategy, this may be accomplished using this library. diff --git a/docs/_build_html/_sources/components/IDGeneration0.rst.txt b/docs/_build_html/_sources/components/IDGeneration0.rst.txt new file mode 100644 index 0000000..9ad5cee --- /dev/null +++ b/docs/_build_html/_sources/components/IDGeneration0.rst.txt @@ -0,0 +1,141 @@ +.. ID Generation: + +================ +ID Generation +================ + +When sharding your data there are a few important upfront decisions to make, one +of the most important ones is how identify each of your models. There are several +common strategies and this library allows you to configure this yourself if you +know the strategy you'd like to use. + +The reason this becomes important is that once you pick a strategy, those ids +will be used in your foreign keys and it will be difficult to change. There +are a few common strategies, most of which come shipped with the package. + +1) Unique shard IDs generated using the time +-------------------------------------------- + +This strategy uses a 64 bit integer to encode the time the item was created, the +shard it was created on and a counter. It works by creating a counter on each of +the shards. It allows you to store as many unique combinations of time, +shard and counter as can fit in that 64 bit integer, which is 1000 per shard per +millisecond. + +i.e. the integer 3863625104385 + +:: + + from datetime import datetime + + id = 3863625104385 + + date_created = datetime.fromtimestamp(((id >> 23) + 1476914064192)/ 1000) + # datetime.datetime(2016, 10, 19, 18, 2, 4, 772000) + + counter = int(bin(id)[-10:], 2) + # 1st object created + + shard = int(bin(id)[-23:-10], 2) + # 31st shard + + +This method supports up to 8192 shards (13 bits) and up to 1024 inserts per +millisecond (10 bits). this should be more than enough for most use cases as +it has been used in places like Instagram where scale is an issue. + + +Note: While I have only included the Postgres implimentation of this so far, it is not +difficult to adapt this for other databases (PRs welcome!). + + +2) Use a UUID & shard id combination +------------------------------------ + +This is a much simpler route and has the benefit of being easier to understand +as each of the ids is just a concatenation or a uuid and a shard's id. The +downside to this approach is that if you ever needed to move a record from one +database to another, there can be uuid collisions (even if those are fairly +unlikely). + + +3) Use a simple integer +----------------------- + +Instead of generating more complicated IDs, if we use a counter or sequence on +the main database to generate the IDs then we can use an integer to have unique +IDs across all the shards as the counter's increment is atomic and thus we have +no issues with collisions. Note: I have not included this implementation in the +package yet. + +The included implementation of this uses a table on the main database rather +than a counter to proxy the auto incrementing field's counter. This was included +as this package was created in part to replace an existing system that worked +this way. + + +Writing Your Own +---------------- + +When writing your own, you must provide a class with a `get_next_id` method on +it. There are no other specific requirements, as you can also implement the +caller and provide any args needed. + +:: + + class BaseIDGenerationStrategy(object): + """ + A strategy for Generating unique identifiers. + """ + def get_next_id(self, database=None): + """ + A function which returns a new unique identifier. + """ + raise NotImplemented + + +Pinterest +--------- + +They recently wrote a `lovely article `_ +about their sharding strategy. They use a 64 bit ID that works like so: + + +:: + + def create_item_id(self, database, model_class, local_id): + return ( + (self.database_name_to_id_map[database] << 46) | + (self.model_to_id_map[model_class] << 36) | + (local_id <<0) + ) + + def get_info_from_item_id(self, item_id): + database_id = (item_id >> 46) & 0xFFFF + model_id = (item_id >> 36) & 0x3FF + local_id = (item_id >> 0) & 0xFFFFFFFFF + return ( + self.database_id_to_name_map[database_id], + model_id_to_class_map[model_id], + local_id + ) + +By using the above method to reference items, you need not choose an explicit ID +generation method and instead the `local_id` can simply by an autoincrementing +field on that table. + +That field would look something like this: + +:: + + class ShardedLocalIDField(ShardedIDFieldMixin, AutoField): + def __init__(self, *args, **kwargs): + kwargs['strategy'] = None + return super(ShardedLocalIDField, self).__init__(*args, **kwargs) + + def get_pk_value_on_save(self, instance): + return super(AutoField, self).get_pk_value_on_save(instance) + + +While I have not included all of the code required to use this type of sharding +strategy, this may be accomplished using this library. diff --git a/docs/_build_html/_sources/components/OtherComponents.rst.txt b/docs/_build_html/_sources/components/OtherComponents.rst.txt new file mode 100644 index 0000000..81da52f --- /dev/null +++ b/docs/_build_html/_sources/components/OtherComponents.rst.txt @@ -0,0 +1,540 @@ +.. Other Components: + +================ +Other Components +================ + +A quick run through of some of the other components shipped with the library. + +Decorators +---------- + +Model Configuration Decorator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +One of the decorators provided is used to label where a model will be stored, +wether it be on a single shard or across many. This decorator also does some +validation that the model is set up correctly. + +It does the following: +1) Validates that the primary key is shard aware by checking that it included +the sharded mixin. + +2) That the model is being stored on only primary databases. + +3) That any postgres specific fields are being used on postgres databases. + +4) Provides a hook for some extra magic (always be careful when using magic) to +remove most cases of the `using` param from lookups where the params are enough +to determine which shard to use. + + +Shard Storage Decorator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A decorator used to mark which models store the shard and which shard group to +use: + +:: + + def shard_storage_config(shard_group='default', shared_field='shard'): + def configure(cls): + setattr(cls, 'django_sharding__shard_group', shard_group) + setattr(cls, 'django_sharding__shard_field', shared_field) + setattr(cls, 'django_sharding__stores_shard', True) + return cls + return configure + + +Fields +------ + +Note: all fields given must remove the custom kwargs from their kwargs before +calling `__init__` on `super` and replace them after calling `deconstruct` on +`super` in order to prevent these arguments from being based on to the +migration and subsequently the database. + + +Sharded ID Fields +----------------- + +This package ships with the mixin required to create you own sharded ID fields +as well as a few basic ones. + +The Sharded ID Field Mixin +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + class ShardedIDFieldMixin(object): + """ + A field which takes an id generator class instance as an + argument and uses the generator to assign each new object + a unique id. + """ + def __init__(self, *args, **kwargs): + # Remove the strategy from the kwargs so that it doesn't + # get passed to Django. + setattr(self, 'strategy', kwargs['strategy']) + del kwargs['strategy'] + return super(ShardedIDFieldMixin, self).__init__( + *args, **kwargs + ) + + def deconstruct(self): + name, path, args, kwargs = super( + ShardedIDFieldMixin, self + ).deconstruct() + + # Add the strategy from the kwargs so that it does get + # passed to our model. + kwargs['strategy'] = getattr(self, 'strategy') + return name, path, args, kwargs + + def get_pk_value_on_save(self, instance): + if not instance.pk: + return self.strategy.get_next_id() + return instance.pk + + +UUID4 Sharded ID Field +^^^^^^^^^^^^^^^^^^^^^^ + +This is an exmaple using the above mixin to generate a uuid and +use that uuid in combination with the shard to generate a unique +ID. + +:: + + class ShardedUUID4Field(ShardedIDFieldMixin, CharField): + def __init__(self, *args, **kwargs): + from app.shardng_strategies import UUIDStrategy + kwargs['strategy'] = UUIDStrategy() + return super(ShardedUUID4Field, self).__init__( + *args, **kwargs + ) + + def get_pk_value_on_save(self, instance): + shard = instance.get_shard() + return self.strategy.get_next_id(shard) + + +Sharded Storage Field +--------------------- + +The most common use case is to store the shard on one of the +models. Included in this package is a mixin that helps do that. + + +Storing The Shard On The Same Object: Shard Storage CharField +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For example, in this case we will be storing the shard in a +`CharField` but we could have used another type of field. + +The field takes the `shard_group` as a key word argument and sets +the field up to makes use of a signal to save the shard (which we +will go into later). + +:: + + class ShardStorageFieldMixin(object): + """ + A mixin for a field used to store a shard for in + an instance or parent of an instance. + """ + def __init__(self, *args, **kwargs): + setattr( + self, 'django_sharding__stores_shard', True + ) + setattr( + self, + 'django_sharding__shard_group', + kwargs['shard_group'] + ) + del kwargs['shard_group'] + return super(ShardStorageFieldMixin, self).__init__( + *args, **kwargs + ) + + def deconstruct(self): + name, path, args, kwargs = super( + ShardStorageFieldMixin, self + ).deconstruct() + kwargs['shard_group'] = getattr( + self, 'django_sharding__shard_group' + ) + return name, path, args, kwargs + + + class ShardLocalStorageFieldMixin(ShardStorageFieldMixin): + """ + The ShardLocalStorageFieldMixin is used for when the shard + is stored on the model that is being sharded by. + i.e. Storing the shard on the User model and sharding by + the User. + """ + def __init__(self, *args, **kwargs): + setattr(self, 'django_sharding__use_signal', True) + return super( + ShardLocalStorageFieldMixin, self + ).__init__(*args, **kwargs) + + def deconstruct(self): + return super( + ShardLocalStorageFieldMixin, self + ).deconstruct() + + + class ShardStorageCharField(ShardLocalStorageFieldMixin, CharField): + """ + A simple char field that stores a shard and uses a signal + to generate the shard using a pre_save signal. + """ + pass + + +Storing The Shard On Another Model Shard Foreign Key Storage Field +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As an example, say we have a webapp that serves all TD banks and +we wish to store all the branches within a district under the same +shard. + +We could store the shard on the district but perhaps we don't +usually touch the district or need to check it and would rather +store the shard on the branch itself but still shard by district. + +One solution is to use a unqiue `shard_key` field on another table +to store the shards and create a foreign key to that table. That +implimentation has been included in this library. + +We will use the method `pre_save` to store the shard. Notice once +again that we are loading the strategy from the AppConfig, which +we will go through soon. + + +:: + + class ShardFKStorageFieldMixin(ShardStorageFieldMixin): + """ + A mixin for a field used to store a foreign key to another + table which stores the shard, usually a table which inherits + from the ShardStorageModel. + """ + def __init__(self, *args, **kwargs): + setattr(self, 'django_sharding__stores_shard', True) + model_class = kwargs.get('to', args and args[0]) + if type(model_class) == str: + app_label = model_class.split('.')[0] + app = apps.get_app_config(app_label) + model_class = app.get_model( + model_class[len(app_label) + 1:] + ) + setattr( + self, + 'django_sharding__shard_storage_table', + model_class + ) + return super( + ShardFKStorageFieldMixin, self + ).__init__(*args, **kwargs) + + def pre_save(self, model_instance, add): + result = super( + ShardFKStorageFieldMixin, self + ).pre_save(model_instance, ad) + self.save_shard(model_instance) + return result + + def save_shard(self, model_instance): + shard_key = model_instance.get_shard_key() + if not getattr(model_instance, self.name): + storage_table = getattr( + self, 'django_sharding__shard_storage_table' + ) + shard_group = getattr( + self, 'django_sharding__shard_group' + ) + + sharding_app = apps.get_app_config('django_sharding') + bucketer = sharding_app.get_bucketer(shard_group) + shard = bucketer.pick_shard(model_instance) + shard_object, _ = storage_table.objects.get_or_create( + shard_key=shard_key + ) + if not shard_object.shard: + shard_object.shard = shard + shard_object.save() + setattr(model_instance, self.name, shard_object) + + + class ShardFKStorageField(ShardFKStorageFieldMixin, ForeignKey): + """ + A simple char field that stores a shard and uses a signal + to generate the shard using a pre_save signal. + """ + pass + + +Models +------ + +Several models are included to help with sharding your applications. + +Shard By Mixin +^^^^^^^^^^^^^^ + +A mixin which add a field to shard by to a model. This also flags +the model to use the included signal (unless the settings is set +to off) to save the shard automatically to this field. + +:: + + def _get_primary_shards(): + """ + Returns the names of databases which make up the shards + and have no primary. + """ + return [ + database_name for (database_name, db_settings) in + settings.DATABASES.items() + if not db_settings.get('PRIMARY', None) and + db_settings.get('SHARD_GROUP', None) + ] + + class ShardedByMixin(models.Model): + django_sharding__shard_field = 'shard' + django_sharding__stores_shard = True + + SHARD_CHOICES = ((i, i) for i in _get_primary_shards()) + + shard = models.CharField( + max_length=120, blank=True, + null=True, choices=SHARD_CHOICES + ) + + class Meta: + abstract = True + + +Table Strategy Model +^^^^^^^^^^^^^^^^^^^^ + +Before when we talked about the `TableShardedIDField` for using +an auto-incriment field to generate unique IDs for items, we +required a table to store that information as an argument to +that field. Such a table is included to inherit from: + +:: + + class TableStrategyModel(models.Model): + id = BigAutoField(primary_key=True) + stub = models.NullBooleanField( + null=True, default=True, unique=True + ) + + class Meta: + abstract = True + + + +Shard Storage Mixin +^^^^^^^^^^^^^^^^^^^ + +Before when we talked about the `ShardForeignKeyStorageField`, we +discussed needing a table to store the shard that uses a +`shard_key` as a primary key on that table to ensure the +`shard_key` will only ever be assigned a single shard. + +Here's an included version of that table to inherit from: + +:: + + class ShardStorageModel(models.Model): + SHARD_CHOICES = ((i, i) for i in _get_primary_shards()) + + shard = models.CharField( + max_length=120, choices=SHARD_CHOICES + ) + shard_key = models.CharField( + primary_key=True, max_length=120 + ) + + class Meta: + abstract = True + + +Signals +------- + +We include one signal in the library which uses the attributes +added by the other components in order to save shards to models +when they are created. + +The `magic` part which automatically runs this is in the app +config which is the last component we'll discuss. + + +:: + + def save_shard_handler(sender, instance, **kwargs): + sharding_app = apps.get_app_config('django_sharding') + bucketer = sharding_app.get_bucketer(sender.shard_group) + + conditional_name = 'django_sharding__stores_shard' + shard_fields = list(filter( + lambda field: getattr(field, conditional_name, False), + sender._meta.fields + )) + + location_name = 'django_sharding__shard_field' + if len(shard_fields) != 1: + shard_field_name = getattr(sender, location_name, None) + shard_fields = list(filter( + lambda field: field.name == shard_field_name, + sender._meta.fields + )) + + if not any(shard_fields): + return + + if len(shard_fields) > 1: + raise Exception( + 'The model {} has multuple fields ' + 'for shard storage: {}'.format( + sender, shard_fields + ) + ) + shard_field = shard_fields[0] + if not getattr(instance, shard_field.name, None): + shard = bucketer.pick_shard(instance) + setattr(instance, shard_field.name, shard) + + +The App Config +-------------- + +In order to automate the magic for most users, there is an +included app configuration in the `django_shard` app. We'll go +through it in steps. + +First it grabs the shard information and initializes the +strategies chosen by the user. This is done through the settings +which we'll go through in the installation step. + + +:: + + shard_settings = getattr( + settings, 'DJANGO_SHARDING_SETTINGS', {} + ) + shard_groups = [ + settings.DATABASES[db_settings]['SHARD_GROUP'] + for db_settings in settings.DATABASES + ] + shard_groups = set( + filter(lambda group: group is not None, shard_groups) + ) + self.bucketers = {} + self.routing_strategies = {} + for shard_group in shard_groups: + group_settings = shard_settings.get(shard_group, {}) + self.bucketers[shard_group] = group_settings.get( + 'BUCKETING_STRATEGY', + RoundRobinBucketingStrategy( + shard_group=shard_group, databases=settings.DATABASES + ) + ) + self.routing_strategies[shard_group] = group_settings.get( + 'ROUTING_STRATEGY', + PrimaryOnlyRoutingStrategy(databases=settings.DATABASES) + ) + + +Then, once the strategies are known for each of the shard groups, +the models that each shard group are sharded on are examined. + +When a sharded model is found, it is assumed that the developer +wanted the signal to be added to automatically save the shard to +the item of the items you're sharding by. For example, a User with +a shard field will automatically have the shard saved to the user +unless set to not do so. + +:: + + for model in apps.get_models(): + shard_group = getattr( + model, 'django_sharding__shard_group', None + ) + stores_shard = getattr( + model, 'django_sharding__stores_shard', False + ) + + if stores_shard and shard_group: + shard_field = getattr( + model, 'django_sharding__shard_field', None + ) + if not shard_field: + raise Exception( + 'The model {} must have a `shard_field` ' + 'attribute'.format(model) + ) + else: + shard_fields = filter( + lambda field: getattr( + field, 'django_sharding__stores_shard', False + ), + model._meta.fields + ) + if not any(shard_fields): + continue + + if len(shard_fields) > 1: + raise Exception( + 'The model {} has multuple fields for shard ' + 'storage: {}'.format( + model, shard_fields) + ) + shard_field = shard_fields[0] + shard_group = getattr( + shard_field, 'django_sharding__shard_group', None + ) + + if not shard_group: + raise Exception( + 'The model {} with the shard field must have ' + 'a `shard_group` attribute'.format(model) + ) + + if not getattr( + shard_field, 'django_sharding__use_signal', False + ): + continue + + group_settings = shard_settings.get(shard_group, {}) + if group_settings.get('SKIP_ADD_SHARDED_SIGNAL', False): + continue + + receiver( + models.signals.pre_save, sender=model + )(save_shard_handler) + + +In order to later retrieve these strategies, two functions are +added to the app configuration so that any other code can +access them: + +:: + + class ShardingConfig(AppConfig): + name = 'django_sharding' + + def ready(self): + pass # The above code went in here. + + def get_routing_strategy(self, shard_group): + return self.routing_strategies[shard_group] + + def get_bucketer(self, shard_group): + return self.bucketers[shard_group] diff --git a/docs/_build_html/_sources/components/ReadStrategies.rst.txt b/docs/_build_html/_sources/components/ReadStrategies.rst.txt new file mode 100644 index 0000000..79102c2 --- /dev/null +++ b/docs/_build_html/_sources/components/ReadStrategies.rst.txt @@ -0,0 +1,164 @@ +.. Read Strategies: + +================ +Read Strategies +================ + +For some applications, reading one shards data from a single copy is not +sufficient and you'll want to use read replicas. While sharding should already +help distribute the load of reads across the system, this package allows you to +configure how to read data if there are replicas in your system. + + +A read strategy looks something like this: + +:: + + class BaseRoutingStrategy(object): + """ + A base strategy for picking which database to read from when + there are read replicas in the system. In order to extend this + strategy, you must define a `pick_read_db` function which + returns the name of the DB to read from, given a primary DB. + If there are no read replicas defined, all strategies should + always return the primary. + """ + def __init__(self, databases): + self.primary_replica_mapping = self.get_replica_mapping( + databases + ) + + def get_replica_mapping(self, databases): + """ + Creates a dictionary that maps a primary drive name to all + the names of it's replication databases. This can be used + in the strategies. + """ + mapping = {} + for name, config in databases.items(): + primary = config.get('PRIMARY', None) + if not primary: + continue + if primary not in mapping: + mapping[primary] = [] + if primary != name: + mapping[primary].append(name) + return mapping + + def pick_read_db(self, primary_db_name): + """ + Given the name of a primary, pick the name of the database + to read from which may be a replica or the primary itself. + """ + raise NotImplemented + + +Here we'll go through some of the included strategies: + + +Primary Only Read Strategy +-------------------------- + +A strategy that ignores existing replication databases and will always choose +the primary database unless instructed otherwise. + +:: + + class PrimaryOnlyRoutingStrategy(BaseRoutingStrategy): + """ + A strategy which will always read from the primary, + unless overridden, regardless of replicas defined. + """ + def pick_read_db(self, primary_db_name): + return primary_db_name + + +Random Read Strategy +-------------------- + +If you don't have an opinion on the load on each node, you may want to simply +choose a random place to read from each time. + +:: + + class RandomRoutingStrategy(BaseRoutingStrategy): + """ + A strategy which will choose a random read replicas, + or the primary, when choosing which database to read from. + """ + def pick_read_db(self, primary_db_name): + replicas = self.primary_replica_mapping[primary_db_name] + return choice(replicas + [primary_db_name]) + + +Round Robin Read Strategy +------------------------- + +This is similar to the sharding function in that it should provide a well +rounded solution to picking a database and split the load evenly. In order to +reduce load imbalance due to the app being restarted, you may want to choose a +random DB to start with here as well. + +:: + + class RoundRobinRoutingStrategy(BaseRoutingStrategy): + """ + A strategy which will cycle through the read replicas and + primary, in a round-robin fashion when choosing which + database to read from. + """ + def __init__(self, databases): + super(RoundRobinRoutingStrategy, self).__init__( + databases + ) + self.read_cycles = {} + + mappings = self.primary_replica_mapping + for primary, replicas in mappings.items(): + self.read_cycles[primary] = cycle(replicas + [primary]) + + def pick_read_db(self, primary_db_name): + return next(self.read_cycles[primary_db_name]) + + +Ratio Routing Strategy +---------------------- + +Here I've provided a basic example, but you could choose to split it up across +all the databases at any ratio. + +For example, you may want to read from the primary drive ten percent of the +time, replica 1 forty percent of the time and replica 2 fifty percent of the +time. + +Here's the example implementation: + +:: + + class ExampleRatioRoutingStrategy(BaseRoutingStrategy): + def pick_read_db(self, primary_db_name): + num = randint(0, 10): + if num == 0: + return primary_db_name + elif num < 5: + return self.primary_replica_mapping[primary_db_name][0] + return self.primary_replica_mapping[primary_db_name][1] + + +Note About Using Read Strategies +-------------------------------- + +If you're using one of the above, or a custom read strategy, there are some +considerations that are important when choosing them. + +The system currently does not have a built-in system to handle replication lag +time. + +For example, if a user updates item A in the primary database then reading from +a replication database before that data has propagated will result in the user +getting stale data. This is typically handled by reading only from the primary +drive during this period, however the system does not include these tools and +additional tools would be required for that. + +For more information, check out the section where we discuss replication lag +time. diff --git a/docs/_build_html/_sources/components/Router.rst.txt b/docs/_build_html/_sources/components/Router.rst.txt new file mode 100644 index 0000000..f320e28 --- /dev/null +++ b/docs/_build_html/_sources/components/Router.rst.txt @@ -0,0 +1,171 @@ +.. The Router: + +================ +The Router +================ + +In this library I've included a single router, which uses the previous +components. Here we will go through the various elements of the router. This +section is meant to explain how the library works and it will be unlikely for +this to be extended or modified unless something custom is needed. + +Note: The utils and helper method's code is not included in this section. + + +Choosing a Database to Read From +-------------------------------- + +The router checks for several conditions in the order of: +1) Is this model stored on only one database, if so then return it. +2) If this model sharded and is the instance called in `hints`, if so then +retrieve the shard. +3) If we have retrieved the shard, then use a read strategy, otherwise we return +None since we do not know where to read it from. + + +:: + + def db_for_read(self, model, **hints): + possible_databases = get_possible_databases_for_model( + model=model + ) + if len(possible_databases) == 1: + return possible_databases[0] + + shard = self._get_shard(model, **hints) + if shard: + shard_group = getattr( + model, 'django_sharding__shard_group', None + ) + if not shard_group: + raise DjangoShardingException( + 'Unable to identify the shard_group for' + + 'the {} model'.format(model) + ) + routing_strategy = self.get_read_db_routing_strategy( + shard_group + ) + return routing_strategy.pick_read_db(shard) + return None + + +Choosing a Database to Write To +-------------------------------- + +This works similarly to the above, except we only return the primary database +rather than using a read strategy. + +:: + + def db_for_write(self, model, **hints): + possible_databases = get_possible_databases_for_model( + model=model + ) + if len(possible_databases) == 1: + return possible_databases[0] + + shard = self._get_shard(model, **hints) + + if shard: + db_config = settings.DATABASES[shard] + return db_config.get('PRIMARY', shard) + return None + + +Can Items Be Related? +--------------------- + +We can only allow relations between items on the same database as you cannot +have a foreign key across a database. + +The router checks for several conditions in the order of: +1) Are both models stored on only one database and are they the same one, if so +then we can allow that relationship. +2) If the above is not true, are these instances on the same database, as that +is the only way they can be related. + +:: + + def allow_relation(self, obj1, obj2, **hints): + """ + Only allow relationships between two items which are + both on only one database or between sharded items on + the same shard. + """ + + object1_databases = get_possible_databases_for_model( + model=obj1._meta.model + ) + object2_databases = get_possible_databases_for_model( + model=obj2._meta.model + ) + + if ( + (len(object1_databases) == len(object2_databases) == 1) and + (object1_databases == object2_databases) + ): + return True + + return ( + self.get_shard_for_instance(obj1) == + self.get_shard_for_instance(obj2) + ) + + +Can I Be Migrated? +------------------ + +When running your migrations, the app needs to be able to determine which +databases require the migration in order to save developers from having to do +this work manually. + +As such, we restrict migrations to run only on the primary databases which store +the model. In the case of sharded models, they are stored on many databases and +each one needs to me migrated. + +By using the module loading system in Django, we can determine the shard status +of a model instance in order to make an informed decision. + + +:: + + def allow_migrate(self, db, app_label, model_name=None, **hints): + if settings.DATABASES[db].get('PRIMARY', None): + return False + + # Since the API for this function is limiting in a sharded + # environemnt, we provide an override to specify which + # databases to run the migrations on. + if hints.get("force_migrate_on_databases", None): + return db in hints["force_migrate_on_databases"] + + model_name = model_name or hints.get('model_name') + model = hints.get('model') + if model: + model_name = model.__name__ + + # Return true if any model in the app is on this database. + if not model_name: + app = apps.get_app_config(app_label) + for model in app.get_models(): + if is_model_class_on_database(model=model, database=db): + return True + return False + + # Sometimes, when extending models from another app the + # the app's name is contained in the `model_name` param + # using the `app.model` syntax. + try: + app = apps.get_app_config(app_label) + model = app.get_model(model_name) + except LookupError: + app_label = model_name.split('.')[0] + app = apps.get_app_config(app_label) + model = app.get_model(model_name[len(app_label) + 1:]) + + try: + return is_model_class_on_database(model=model, database=db) + except DjangoShardingException as e: + raise InvalidMigrationException( + e.args[0] + ) diff --git a/docs/_build_html/_sources/components/ShardingFunctions.rst.txt b/docs/_build_html/_sources/components/ShardingFunctions.rst.txt new file mode 100644 index 0000000..34eb094 --- /dev/null +++ b/docs/_build_html/_sources/components/ShardingFunctions.rst.txt @@ -0,0 +1,171 @@ +.. Sharding Functions: + +================== +Sharding Functions +================== + +A sharding function is a python class that will choose which data belongs on +which database and let us know which database the stored data is on. + +This is split into the two functions `pick_shard` and `get_shard` on a plain +python class. The reason this is split into two different functions is that +there are common sharding functions used that are not deterministic. Since the +generator may be non deterministic then both are implemented separately. An +example of this is to round-robin bucket users into their own shards. + +An interface for a sharding strategy looks as follows: + +:: + + class BaseBucketingStrategy(object): + def __init__(self, shard_group='default'): + self.shard_group = shard_group + + def get_shards(self, databases): + return [ + name for( name, config) in databases + if ( + config.get('SHARD_GROUP') == self.shard_group and + not config.get('PRIMARY') + ) + ] + + def pick_shard(self, model_sharded_by): + """ + Returns the shard for the model which has not previously + been bucketed into a shard. + """ + raise NotImplemented + + def get_shard(self, model_sharded_by): + """ + Returns the shard for a model which has already been + assigned a shard. + """ + raise NotImplemented + + +As I mentioned above, there are are both deterministic and non-deterministic +ways of bucketing into shards. As an example below, I will show the ones +included wit the package. + + +Deterministic Functions +----------------------- + +I have not shipped this package with any truly deterministic functions as I've +yet to come across a need and the example below is brittle as it breaks as soon +as you add more shards to the system. Nonetheless, I have included it for +completeness. + +:: + + class ModBucketingStrategy(BaseBucketingStrategy): + """ + A shard selection strategy that assigns shards based on the mod + of the models pk. + """ + def __init__(self, shard_group, databases): + super(RoundRobinBucketingStrategy, self).__init__( + shard_group + ) + self.shards = self.get_shards(databases) + self.shards.sort() + + def pick_shard(self, model_sharded_by): + return self.shards[ + hash(str(model_sharded_by.pk)) % len(self.shards) + ] + + def get_shard(self, model_sharded_by): + return self.pick_shard(model_sharded_by) + + +Non-deterministic Functions +--------------------------- + +Random Bucketing Strategy +^^^^^^^^^^^^^^^^^^^^^^^^^ + +As the name says, this method chooses a random shard and ends up storing it on +the model in question. + +:: + + class RandomBucketingStrategy(BaseShardedModelBucketingStrategy): + """ + A shard selection strategy that assigns shards randomly. + This is non-deterministic and this strategy assumes the shard + is saved to the model. + """ + def __init__(self, shard_group, databases): + super(RoundRobinBucketingStrategy, self).__init__( + shard_group + ) + self.shards = self.get_shards(databases) + + def pick_shard(self, model_sharded_by): + return choice(self.shards) + + def get_shard(self, model_sharded_by): + return model_sharded_by.shard + + +Round-Robin Bucketing Strategy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This uses a round-robin approach to choose a shard in order to maintain a +balance across the system so that the proportion of new instances is even +across the shards: + +:: + + class RoundRobinBucketingStrategy(BaseShardedModelBucketingStrategy): + def __init__(self, shard_group, databases): + super(RoundRobinBucketingStrategy, self).__init__( + shard_group + ) + + shards = self.get_shards(databases) + max_index = max(0, len(shards) - 1) + starting_index = randint(0, max_index) + + shards = shards[starting_index:] + shards[:starting_index] + self._shards_cycle = cycle(shards) + + def pick_shard(self, model_sharded_by): + return next(self._shards_cycle) + + def get_shard(self, model_sharded_by): + return model_sharded_by.shard + + +Since this is initialized at app initialization time, it begins the cycle at a +random index, otherwise the first shard would always be imbalanced. + +Mod Bucketing Strategy +^^^^^^^^^^^^^^^^^^^^^^ + +This works the same way as the non-deterministic strategy but allows you to add +shards by storing them on the model. + +:: + + class ModBucketingStrategy(BaseBucketingStrategy): + """ + A shard selection strategy that assigns shards based on the mod of the + models pk. + """ + def __init__(self, shard_group, databases): + super(RoundRobinBucketingStrategy, self).__init__( + shard_group + ) + self.shards = self.get_shards(databases) + + def pick_shard(self, model_sharded_by): + return self.shards[ + hash(str(model_sharded_by.pk)) % len(self.shards) + ] + + def get_shard(self, model_sharded_by): + return model_sharded_by.shard diff --git a/docs/_build_html/_sources/index.rst.txt b/docs/_build_html/_sources/index.rst.txt new file mode 100644 index 0000000..5e5e8bd --- /dev/null +++ b/docs/_build_html/_sources/index.rst.txt @@ -0,0 +1,26 @@ +.. Django Sharding documentation master file, created by + sphinx-quickstart on Sun Feb 19 13:05:20 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Django Sharding's documentation! +=========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Components: + + + ID Generation + Sharding Functions + Read Strategies + The Router + Other Components + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/_build_html/_static/ajax-loader.gif b/docs/_build_html/_static/ajax-loader.gif new file mode 100644 index 0000000..61faf8c Binary files /dev/null and b/docs/_build_html/_static/ajax-loader.gif differ diff --git a/docs/_build_html/_static/alabaster.css b/docs/_build_html/_static/alabaster.css new file mode 100644 index 0000000..a88ce29 --- /dev/null +++ b/docs/_build_html/_static/alabaster.css @@ -0,0 +1,693 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif; + font-size: 17px; + background-color: #fff; + color: #000; + margin: 0; + padding: 0; +} + + +div.document { + width: 940px; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 220px; +} + +div.sphinxsidebar { + width: 220px; + font-size: 14px; + line-height: 1.5; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #fff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +div.body > .section { + text-align: left; +} + +div.footer { + width: 940px; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +p.caption { + font-family: inherit; + font-size: inherit; +} + + +div.relations { + display: none; +} + + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0; + margin: -10px 0 0 0px; + text-align: center; +} + +div.sphinxsidebarwrapper h1.logo { + margin-top: -10px; + text-align: center; + margin-bottom: 5px; + text-align: left; +} + +div.sphinxsidebarwrapper h1.logo-name { + margin-top: 0px; +} + +div.sphinxsidebarwrapper p.blurb { + margin-top: 0; + font-style: normal; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: 'Garamond', 'Georgia', serif; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar ul li.toctree-l1 > a { + font-size: 120%; +} + +div.sphinxsidebar ul li.toctree-l2 > a { + font-size: 110%; +} + +div.sphinxsidebar input { + border: 1px solid #CCC; + font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif; + font-size: 1em; +} + +div.sphinxsidebar hr { + border: none; + height: 1px; + color: #AAA; + background: #AAA; + + text-align: left; + margin-left: 0; + width: 50%; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #DDD; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; + background: #EAEAEA; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + margin: 20px 0px; + padding: 10px 30px; + background-color: #EEE; + border: 1px solid #CCC; +} + +div.admonition tt.xref, div.admonition code.xref, div.admonition a tt { + background-color: ; + border-bottom: 1px solid #fafafa; +} + +dd div.admonition { + margin-left: -60px; + padding-left: 60px; +} + +div.admonition p.admonition-title { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: #fff; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.warning { + background-color: #FCC; + border: 1px solid #FAA; +} + +div.danger { + background-color: #FCC; + border: 1px solid #FAA; + -moz-box-shadow: 2px 2px 4px #D52C2C; + -webkit-box-shadow: 2px 2px 4px #D52C2C; + box-shadow: 2px 2px 4px #D52C2C; +} + +div.error { + background-color: #FCC; + border: 1px solid #FAA; + -moz-box-shadow: 2px 2px 4px #D52C2C; + -webkit-box-shadow: 2px 2px 4px #D52C2C; + box-shadow: 2px 2px 4px #D52C2C; +} + +div.caution { + background-color: #FCC; + border: 1px solid #FAA; +} + +div.attention { + background-color: #FCC; + border: 1px solid #FAA; +} + +div.important { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.note { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.tip { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.hint { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.seealso { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.topic { + background-color: #EEE; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt, code { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; +} + +.hll { + background-color: #FFC; + margin: 0 -12px; + padding: 0 12px; + display: block; +} + +img.screenshot { +} + +tt.descname, tt.descclassname, code.descname, code.descclassname { + font-size: 0.95em; +} + +tt.descname, code.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #EEE; + -webkit-box-shadow: 2px 2px 4px #EEE; + box-shadow: 2px 2px 4px #EEE; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #EEE; + -webkit-box-shadow: 2px 2px 4px #EEE; + box-shadow: 2px 2px 4px #EEE; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #EEE; + background: #FDFDFD; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.field-list p { + margin-bottom: 0.8em; +} + +table.footnote td.label { + width: .1px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + /* Matches the 30px from the narrow-screen "li > ul" selector below */ + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #EEE; + padding: 7px 30px; + margin: 15px 0px; + line-height: 1.3em; +} + +div.viewcode-block:target { + background: #ffd; +} + +dl pre, blockquote pre, li pre { + margin-left: 0; + padding-left: 30px; +} + +dl dl pre { + margin-left: -90px; + padding-left: 90px; +} + +tt, code { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, code.xref, a tt { + background-color: #FBFBFB; + border-bottom: 1px solid #fff; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #004B6B; +} + +/* Don't put an underline on images */ +a.image-reference, a.image-reference:hover { + border-bottom: none; +} + +a.reference:hover { + border-bottom: 1px solid #6D4100; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #004B6B; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #6D4100; +} + +a:hover tt, a:hover code { + background: #EEE; +} + + +@media screen and (max-width: 870px) { + + div.sphinxsidebar { + display: none; + } + + div.document { + width: 100%; + + } + + div.documentwrapper { + margin-left: 0; + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + } + + div.bodywrapper { + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + margin-left: 0; + } + + ul { + margin-left: 0; + } + + li > ul { + /* Matches the 30px from the "ul, ol" selector above */ + margin-left: 30px; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .bodywrapper { + margin: 0; + } + + .footer { + width: auto; + } + + .github { + display: none; + } + + + +} + + + +@media screen and (max-width: 875px) { + + body { + margin: 0; + padding: 20px 30px; + } + + div.documentwrapper { + float: none; + background: #fff; + } + + div.sphinxsidebar { + display: block; + float: none; + width: 102.5%; + margin: 50px -30px -20px -30px; + padding: 10px 20px; + background: #333; + color: #FFF; + } + + div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, + div.sphinxsidebar h3 a { + color: #fff; + } + + div.sphinxsidebar a { + color: #AAA; + } + + div.sphinxsidebar p.logo { + display: none; + } + + div.document { + width: 100%; + margin: 0; + } + + div.footer { + display: none; + } + + div.bodywrapper { + margin: 0; + } + + div.body { + min-height: 0; + padding: 0; + } + + .rtd_doc_footer { + display: none; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .footer { + width: auto; + } + + .github { + display: none; + } +} + + +/* misc. */ + +.revsys-inline { + display: none!important; +} + +/* Make nested-list/multi-paragraph items look better in Releases changelog + * pages. Without this, docutils' magical list fuckery causes inconsistent + * formatting between different release sub-lists. + */ +div#changelog > div.section > ul > li > p:only-child { + margin-bottom: 0; +} + +/* Hide fugly table cell borders in ..bibliography:: directive output */ +table.docutils.citation, table.docutils.citation td, table.docutils.citation th { + border: none; + /* Below needed in some edge cases; if not applied, bottom shadows appear */ + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} \ No newline at end of file diff --git a/docs/_build_html/_static/basic.css b/docs/_build_html/_static/basic.css new file mode 100644 index 0000000..7ed0e58 --- /dev/null +++ b/docs/_build_html/_static/basic.css @@ -0,0 +1,632 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox input[type="text"] { + width: 170px; +} + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlighted { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +div.code-block-caption { + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +div.code-block-caption + div > div.highlight > pre { + margin-top: 0; +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + padding: 1em 1em 0; +} + +div.literal-block-wrapper div.highlight { + margin: 0; +} + +code.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +code.descclassname { + background-color: transparent; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: relative; + left: 0px; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/docs/_build_html/_static/comment-bright.png b/docs/_build_html/_static/comment-bright.png new file mode 100644 index 0000000..15e27ed Binary files /dev/null and b/docs/_build_html/_static/comment-bright.png differ diff --git a/docs/_build_html/_static/comment-close.png b/docs/_build_html/_static/comment-close.png new file mode 100644 index 0000000..4d91bcf Binary files /dev/null and b/docs/_build_html/_static/comment-close.png differ diff --git a/docs/_build_html/_static/comment.png b/docs/_build_html/_static/comment.png new file mode 100644 index 0000000..dfbc0cb Binary files /dev/null and b/docs/_build_html/_static/comment.png differ diff --git a/docs/_build_html/_static/custom.css b/docs/_build_html/_static/custom.css new file mode 100644 index 0000000..2a924f1 --- /dev/null +++ b/docs/_build_html/_static/custom.css @@ -0,0 +1 @@ +/* This file intentionally left blank. */ diff --git a/docs/_build_html/_static/doctools.js b/docs/_build_html/_static/doctools.js new file mode 100644 index 0000000..8163495 --- /dev/null +++ b/docs/_build_html/_static/doctools.js @@ -0,0 +1,287 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this); + }); + } + } + return this.each(function() { + highlight(this); + }); +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + if (!body.length) { + body = $('body'); + } + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('

' + _('Hide Search Matches') + '

') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + }, + + initOnKeyListeners: function() { + $(document).keyup(function(event) { + var activeElementType = document.activeElement.tagName; + // don't navigate when in search box or textarea + if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') { + switch (event.keyCode) { + case 37: // left + var prevHref = $('link[rel="prev"]').prop('href'); + if (prevHref) { + window.location.href = prevHref; + return false; + } + case 39: // right + var nextHref = $('link[rel="next"]').prop('href'); + if (nextHref) { + window.location.href = nextHref; + return false; + } + } + } + }); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); \ No newline at end of file diff --git a/docs/_build_html/_static/down-pressed.png b/docs/_build_html/_static/down-pressed.png new file mode 100644 index 0000000..5756c8c Binary files /dev/null and b/docs/_build_html/_static/down-pressed.png differ diff --git a/docs/_build_html/_static/down.png b/docs/_build_html/_static/down.png new file mode 100644 index 0000000..1b3bdad Binary files /dev/null and b/docs/_build_html/_static/down.png differ diff --git a/docs/_build_html/_static/file.png b/docs/_build_html/_static/file.png new file mode 100644 index 0000000..a858a41 Binary files /dev/null and b/docs/_build_html/_static/file.png differ diff --git a/docs/_build_html/_static/jquery-3.1.0.js b/docs/_build_html/_static/jquery-3.1.0.js new file mode 100644 index 0000000..f2fc274 --- /dev/null +++ b/docs/_build_html/_static/jquery-3.1.0.js @@ -0,0 +1,10074 @@ +/*eslint-disable no-unused-vars*/ +/*! + * jQuery JavaScript Library v3.1.0 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright jQuery Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + * + * Date: 2016-07-07T21:44Z + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var document = window.document; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var concat = arr.concat; + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + + + + function DOMEval( code, doc ) { + doc = doc || document; + + var script = doc.createElement( "script" ); + + script.text = code; + doc.head.appendChild( script ).parentNode.removeChild( script ); + } +/* global Symbol */ +// Defining this global in .eslintrc would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.1.0", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }, + + // Support: Android <=4.0 only + // Make sure we trim BOM and NBSP + rtrim = /^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g, + + // Matches dashed string for camelizing + rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g, + + // Used by jQuery.camelCase as callback to replace() + fcamelCase = function( all, letter ) { + return letter.toUpperCase(); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + return num != null ? + + // Return just the one element from the set + ( num < 0 ? this[ num + this.length ] : this[ num ] ) : + + // Return all the elements in a clean array + slice.call( this ); + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !jQuery.isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + src = target[ name ]; + copy = options[ name ]; + + // Prevent never-ending loop + if ( target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = jQuery.isArray( copy ) ) ) ) { + + if ( copyIsArray ) { + copyIsArray = false; + clone = src && jQuery.isArray( src ) ? src : []; + + } else { + clone = src && jQuery.isPlainObject( src ) ? src : {}; + } + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isFunction: function( obj ) { + return jQuery.type( obj ) === "function"; + }, + + isArray: Array.isArray, + + isWindow: function( obj ) { + return obj != null && obj === obj.window; + }, + + isNumeric: function( obj ) { + + // As of jQuery 3.0, isNumeric is limited to + // strings and numbers (primitives or objects) + // that can be coerced to finite numbers (gh-2662) + var type = jQuery.type( obj ); + return ( type === "number" || type === "string" ) && + + // parseFloat NaNs numeric-cast false positives ("") + // ...but misinterprets leading-number strings, particularly hex literals ("0x...") + // subtraction forces infinities to NaN + !isNaN( obj - parseFloat( obj ) ); + }, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + + /* eslint-disable no-unused-vars */ + // See https://github.com/eslint/eslint/issues/6125 + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + type: function( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; + }, + + // Evaluates a script in a global context + globalEval: function( code ) { + DOMEval( code ); + }, + + // Convert dashed to camelCase; used by the css and data modules + // Support: IE <=9 - 11, Edge 12 - 13 + // Microsoft forgot to hump their vendor prefix (#9572) + camelCase: function( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); + }, + + nodeName: function( elem, name ) { + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // Support: Android <=4.0 only + trim: function( text ) { + return text == null ? + "" : + ( text + "" ).replace( rtrim, "" ); + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return concat.apply( [], ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // Bind a function to a context, optionally partially applying any + // arguments. + proxy: function( fn, context ) { + var tmp, args, proxy; + + if ( typeof context === "string" ) { + tmp = fn[ context ]; + context = fn; + fn = tmp; + } + + // Quick check to determine if target is callable, in the spec + // this throws a TypeError, but we will just return undefined. + if ( !jQuery.isFunction( fn ) ) { + return undefined; + } + + // Simulated bind + args = slice.call( arguments, 2 ); + proxy = function() { + return fn.apply( context || this, args.concat( slice.call( arguments ) ) ); + }; + + // Set the guid of unique handler to the same of original handler, so it can be removed + proxy.guid = fn.guid = fn.guid || jQuery.guid++; + + return proxy; + }, + + now: Date.now, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), +function( i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); +} ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = jQuery.type( obj ); + + if ( type === "function" || jQuery.isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.0 + * https://sizzlejs.com/ + * + * Copyright jQuery Foundation and other contributors + * Released under the MIT license + * http://jquery.org/license + * + * Date: 2016-01-04 + */ +(function( window ) { + +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ({}).hasOwnProperty, + arr = [], + pop = arr.pop, + push_native = arr.push, + push = arr.push, + slice = arr.slice, + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[i] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // http://www.w3.org/TR/CSS21/syndata.html#value-def-identifier + identifier = "(?:\\\\.|[\\w-]|[^\0-\\xa0])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + // "Attribute values must be CSS identifiers [capture 5] or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + whitespace + + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + "*" ), + + rattributeQuotes = new RegExp( "=" + whitespace + "*([^\\]'\"]*?)" + whitespace + "*\\]", "g" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + whitespace + + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + whitespace + + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + + whitespace + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\([\\da-f]{1,6}" + whitespace + "?|(" + whitespace + ")|.)", "ig" ), + funescape = function( _, escaped, escapedWhitespace ) { + var high = "0x" + escaped - 0x10000; + // NaN means non-codepoint + // Support: Firefox<24 + // Workaround erroneous numeric interpretation of +"0x" + return high !== high || escapedWhitespace ? + escaped : + high < 0 ? + // BMP codepoint + String.fromCharCode( high + 0x10000 ) : + // Supplemental Plane codepoint (surrogate pair) + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\x80-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + disabledAncestor = addCombinator( + function( elem ) { + return elem.disabled === true; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + (arr = slice.call( preferredDoc.childNodes )), + preferredDoc.childNodes + ); + // Support: Android<4.0 + // Detect silently failing push.apply + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + push_native.apply( target, slice.call(els) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + // Can't trust NodeList.length + while ( (target[j++] = els[i++]) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + + if ( ( context ? context.ownerDocument || context : preferredDoc ) !== document ) { + setDocument( context ); + } + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && (match = rquickExpr.exec( selector )) ) { + + // ID selector + if ( (m = match[1]) ) { + + // Document context + if ( nodeType === 9 ) { + if ( (elem = context.getElementById( m )) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && (elem = newContext.getElementById( m )) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[2] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( (m = match[3]) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !compilerCache[ selector + " " ] && + (!rbuggyQSA || !rbuggyQSA.test( selector )) ) { + + if ( nodeType !== 1 ) { + newContext = context; + newSelector = selector; + + // qSA looks outside Element context, which is not what we want + // Thanks to Andrew Dupont for this workaround technique + // Support: IE <=8 + // Exclude object elements + } else if ( context.nodeName.toLowerCase() !== "object" ) { + + // Capture the context ID, setting it first if necessary + if ( (nid = context.getAttribute( "id" )) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", (nid = expando) ); + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[i] = "#" + nid + " " + toSelector( groups[i] ); + } + newSelector = groups.join( "," ); + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + } + + if ( newSelector ) { + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return (cache[ key + " " ] = value); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement("fieldset"); + + try { + return !!fn( el ); + } catch (e) { + return false; + } finally { + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split("|"), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[i] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( (cur = cur.nextSibling) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return (name === "input" || name === "button") && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + // Known :disabled false positives: + // IE: *[disabled]:not(button, input, select, textarea, optgroup, option, menuitem, fieldset) + // not IE: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Check form elements and option elements for explicit disabling + return "label" in elem && elem.disabled === disabled || + "form" in elem && elem.disabled === disabled || + + // Check non-disabled form elements for fieldset[disabled] ancestors + "form" in elem && elem.disabled === false && ( + // Support: IE6-11+ + // Ancestry is covered for us + elem.isDisabled === disabled || + + // Otherwise, assume any non-