### Install python-ldap-faker

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Installs the python-ldap-faker package from PyPI using pip.

```bash
pip install python-ldap-faker
```

--------------------------------

### Install python-ldap-faker

Source: https://github.com/caltechads/python-ldap-faker/blob/master/README.md

Installs the python-ldap-faker package from PyPI using pip. This command is used to set up the library for use in your project.

```shell
pip install python-ldap-faker
```

--------------------------------

### Example Data for Fake LDAP Server

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

An example JSON structure representing 'posixAccount' objects for loading into the fake LDAP server.

```json
[
   [
      "uid=foo,ou=bar,o=baz,c=country",
      {
            "uid": ["foo"],
            "cn": ["Foo Bar"],
            "uidNumber": ["123"],
            "gidNumber": ["123"],
            "homeDirectory": ["/home/foo"],
            "userPassword": ["the password"],
            "objectclass": [
               "posixAccount",
               "top"
            ]
      }
   ],
   [
      "uid=fred,ou=bar,o=baz,c=country",
      {

```

--------------------------------

### Python LDAP Faker Quickstart with unittest

Source: https://github.com/caltechads/python-ldap-faker/blob/master/README.md

Demonstrates how to use `LDAPFakerMixin` with `unittest.TestCase` to mock LDAP operations. It includes setting up fixture data in JSON and writing tests for authentication and connection options.

```json
[
    [
        "uid=foo,ou=bar,o=baz,c=country",
        {
            "uid": ["foo"],
            "cn": ["Foo Bar"],
            "uidNumber": ["123"],
            "gidNumber": ["123"],
            "homeDirectory": ["/home/foo"],
            "userPassword": ["the password"],
            "objectclass": [
                "posixAccount",
                "top"
            ]
        }
    ],
    [
        "uid=fred,ou=bar,o=baz,c=country",
        {
            "uid": ["fred"],
            "cn": ["Fred Flintstone"],
            "uidNumber": ["124"],
            "gidNumber": ["124"],
            "homeDirectory": ["/home/fred"],
            "userPassword": ["the fredpassword"],
            "objectclass": [
                "posixAccount",
                "top"
            ]
        }
    ],
    [
        "uid=barney,ou=bar,o=baz,c=country",
        {
            "uid": ["barney"],
            "cn": ["Barney Rubble"],
            "uidNumber": ["125"],
            "gidNumber": ["125"],
            "homeDirectory": ["/home/barney"],
            "userPassword": ["the barneypassword"],
            "objectclass": [
                "posixAccount",
                "top"
            ]
        }
    ]
]
```

```python
import unittest

import ldap
from ldap_faker import LDAPFakerMixin

from myapp import App

class YourTestCase(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp']
    ldap_fixtures = 'data.json'

    def test_auth_works(self):
        app = App()
        # A method that does a `simple_bind_s`
        app.auth('fred', 'the fredpassword')
        conn = self.get_connections()[0]
        self.assertLDAPConnectionMethodCalled(
            conn, 'simple_bind_s',
            {'who': 'uid=fred,ou=bar,o=baz,c=country', 'cred': 'the fredpassword'}
        )

    def test_correct_connection_options_were_set(self):
        app = App()
        app.auth('fred', 'the fredpassword')
        conn = self.get_connections()[0]
        self.assertLDAPConnectionOptionSet(conn, ldap.OPT_X_TLX_NEWCTX, 0)

    def test_tls_was_used_before_auth(self):
        app = App()
        app.auth('fred', 'the fredpassword')
        conn = self.get_connections()[0]
        self.assertLDAPConnectiontMethodCalled(conn, 'start_tls_s')
        self.assertLDAPConnectionMethodCalledAfter(conn, 'simple_bind_s', 'start_tls_s')
```

--------------------------------

### LDAP Initialization Example

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/unittest.rst

Demonstrates how to initialize an LDAP connection and perform operations within a class that uses python-ldap. This snippet is intended to show the context for patching by LDAPFakerMixin.

```python
import ldap

class MyLDAPUsingClass:

    def connect(self, uid: str, password: str):
        self.conn = ldap.initialize('ldap://server')
        self.conn.set_option(ldap.OPT_X_TLS_NEWCTX, 0)
        self.conn.start_tls_s()
        self.conn.simple_bind_s(
          f'uid={uid},ou=bar,o=baz,c=country',
          'the password'
        )
```

--------------------------------

### Tagging fixtures with 'special'

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Illustrates how to tag LDAP fixtures when using LDAPFakerMixin. This example shows tagging the default server fixture with the 'special' tag.

```python
import unittest
from ldap_faker import LDAPFakerMixin


class TestDefaultTaggedServer(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp']
    ldap_fixtures = ('data.json', ['special'])
```

--------------------------------

### LDAPFakerMixin Test Case Setup (Single Fixture)

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/unittest.rst

Demonstrates configuring LDAPFakerMixin to use a single JSON fixture file for populating the fake LDAP server. This fixture will be used regardless of the LDAP URI passed to ldap.initialize.

```python
import unittest
from ldap_faker import LDAPFakerMixin

from myapp.myldapstuff import MyLDAPUsingClass

class TestMyLDAPUsingCLass(LDAPFakerMixin, unittest.TestCase):

    ldap_fixtures = 'objects.json'
```

--------------------------------

### LDAPFakerMixin Test Case Setup (Modules)

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/unittest.rst

Shows how to configure a unittest.TestCase by inheriting from LDAPFakerMixin and specifying the modules that import and use the ldap library. This ensures that ldap.initialize, ldap.set_option, and ldap.get_option are patched correctly.

```python
import unittest
from ldap_faker import LDAPFakerMixin

from myapp.myldapstuff import MyLDAPUsingClass

class TestMyLDAPUsingCLass(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp.myldapstuff']
```

--------------------------------

### Registering a tagged pre_set hook

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Shows how to register a hook that only runs for ObjectStore instances with specific tags. This example registers a hook for ObjectStore instances tagged with 'special'.

```python
from ldap_faker import hooks, ObjectStore, LDAPRecord


def pre_set_do_something_special(store: ObjectStore, record: LDAPRecord, bind_dn: str = None) -> None:
    print(f'{bind_dn} ran pre_set_do_something_sepcial')

hooks.register('pre_set', pre_set_do_something_special, tags=['special'])
```

--------------------------------

### LDAPFakerMixin Test Case Setup (Multiple Fixtures)

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/unittest.rst

Illustrates how to configure LDAPFakerMixin to use multiple JSON fixture files, each bound to a specific LDAP URI. This allows simulating interactions with different LDAP servers within the same test suite.

```python
import unittest
from ldap_faker import LDAPFakerMixin

from myapp.myldapstuff import MyLDAPUsingClass

class TestMyLDAPUsingCLass(LDAPFakerMixin, unittest.TestCase):

    ldap_fixtures = [
      ('server1.json', 'ldap://server1.example.com'),
      ('server2.json', 'ldap://server2.example.com')
    ]
```

--------------------------------

### LDAPServerFactory - LDAP Server like objects

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

A factory class responsible for creating and managing fake LDAP server instances, simplifying the setup of mock LDAP environments.

```python
class LDAPServerFactory:
    pass
```

--------------------------------

### Tagging named servers

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Demonstrates tagging individual named LDAP servers when using LDAPFakerMixin. This example tags 'server1.json' with 'special' while 'server2.json' uses only untagged hooks.

```python
import unittest
from ldap_faker import LDAPFakerMixin


class TestDefaultTaggedServer(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp']
    ldap_fixtures = [
        ('server1.json', 'ldap://server1', ['special']),
        ('server2.json', 'ldap://server2')
    ]
```

--------------------------------

### Simple Paged Results Control

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/controls.rst

Provides an example of using the SimplePagedResultsControl for paginating LDAP search results. It shows how to create the control, perform a paged search, and iterate through results using cookies.

```python
import ldap
from ldap.controls import SimplePagedResultsControl

# Create paged results control
paged_results_control = SimplePagedResultsControl(
    True,  # critical
    "1000",  # size
    "",  # initial cookie
)

while True:
    # Perform paged search
    msgid = conn.search_ext(
        'ou=users,dc=example,dc=com',
        ldap.SCOPE_SUBTREE,
        '(objectClass=person)',
        serverctrls=[paged_results_control]
    )

    # Retrieve results
    rtype, rdata, rmsgid, rctrls = conn.result3(msgid)

    # Get paged results control
    paged_results_control = rctrls[0]

    # Get paged results cookie
    paged_results_control.cookie = paged_results_control.cookie

    # If there are no more results, break
    if not paged_results_cookie:
        break

    # Update paged results control with new cookie
    paged_results_control.cookie = paged_results_cookie
```

--------------------------------

### LDAP User Data Fixtures

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Example JSON structure representing LDAP user entries, including attributes like uid, cn, uidNumber, gidNumber, homeDirectory, userPassword, and objectclass.

```json
[
   "uid=fred,ou=bar,o=baz,c=country",
   {
      "uid": ["fred"],
      "cn": ["Fred Flintstone"],
      "uidNumber": ["124"],
      "gidNumber": ["124"],
      "homeDirectory": ["/home/fred"],
      "userPassword": ["the fredpassword"],
      "objectclass": [
         "posixAccount",
         "top"
      ]
   }
],
[
   "uid=barney,ou=bar,o=baz,c=country",
   {
      "uid": ["barney"],
      "cn": ["Barney Rubble"],
      "uidNumber": ["125"],
      "gidNumber": ["125"],
      "homeDirectory": ["/home/barney"],
      "userPassword": ["the barneypassword"],
      "objectclass": [
         "posixAccount",
         "top"
      ]
   }
]
]
```

--------------------------------

### Anonymous Bind Example

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/binds.rst

Demonstrates how to perform an anonymous bind to the fake LDAP server using python-ldap-faker. This is a prerequisite for certain LDAP operations.

```python
ldap_obj = fake_ldap.initialize('ldap://server')
ldap_obj.simple_bind_s()
```

```python
ldap_obj = fake_ldap.initialize('ldap://server')
ldap_obj.search_s('ou=bar,o=baz,c=country', ldap.SCOPE_SUBTREE, '(uid=user)')
```

--------------------------------

### Virtual List View (VLV) Request Control Usage

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/controls.rst

Provides an example of creating and using the VLV request control to fetch a specific window of results from an LDAP search.

```python
import ldap
from ldap.controls import LDAPControl

# Create VLV control: get 1 entry before and after position 1
vlv_value = "1,1,1".encode('utf-8')
vlv_control = LDAPControl(
    '2.16.840.1.113730.3.4.9',
    True,
    vlv_value,
)

# Perform VLV search
msgid = conn.search_ext(
    'dc=example,dc=com',
    ldap.SCOPE_SUBTREE,
    '(objectClass=person)',
    serverctrls=[vlv_control]
)

# Get results
rtype, rdata, rmsgid, rctrls = conn.result3(msgid)
```

--------------------------------

### Server Side Sort Control (Single and Multi-key)

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/controls.rst

Demonstrates how to implement Server Side Sort control for ordering LDAP search results. Includes examples for sorting by a single attribute and by multiple attributes, with explanations of the ASN.1 structure for sort keys.

```python
import ldap
from ldap.controls import LDAPControl
from pyasn1.codec.ber import encoder
from pyasn1.type import namedtype, univ

# Define SortKey ASN.1 structure
class SortKey(univ.Sequence):
    componentType = namedtype.NamedTypes(
        namedtype.NamedType("attributeType", univ.OctetString()),
        namedtype.OptionalNamedType("orderingRule", univ.OctetString()),
        namedtype.DefaultedNamedType("reverseOrder", univ.Boolean(False))
    )

class SortKeyList(univ.SequenceOf):
    componentType = SortKey()

# Create sort control for single attribute
sort_key = SortKey()
sort_key.setComponentByName("attributeType", "cn")

sort_key_list = SortKeyList()
sort_key_list.setComponentByPosition(0, sort_key)

encoded_value = encoder.encode(sort_key_list)

sort_control = LDAPControl(
    '1.2.840.113556.1.4.473',
    True,
    encoded_value
)

# Perform sorted search
msgid = conn.search_ext(
    'ou=users,dc=example,dc=com',
    ldap.SCOPE_SUBTREE,
    '(objectClass=person)',
    serverctrls=[sort_control]
)

# Get sorted results
rtype, rdata, rmsgid, rctrls = conn.result3(msgid)

# Multi-key sorting is also supported::

# Create sort control for multiple attributes (sort by cn, then uid)
sort_key_list = SortKeyList()

# First sort key: cn (ascending)
cn_key = SortKey()
cn_key.setComponentByName("attributeType", "cn")
sort_key_list.setComponentByPosition(0, cn_key)

# Second sort key: uid (ascending)
uid_key = SortKey()
uid_key.setComponentByName("attributeType", "uid")

```

--------------------------------

### LDAP Object Data Structure Example

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/objectstore.rst

This snippet illustrates the expected structure for a list of LDAP objects. Each object is represented as a list containing a distinguished name (DN) string and a dictionary of attributes. Attribute values are expected to be lists of strings.

```Python
[
  [
    'uid=foo,ou=bar,o=baz,c=country',
    {
      "uid": ["foo"],
      "cn": ["Foo Bar"],
      "uidNumer": ["123"],
      "gidNumer": ["123"],
      "homeDirectory": ["/home/foo"],
      "userPassword": ["the password"],
      "ojectclass": [
        "posixAccount",
        "top"
      ]
    }
  ]
]
```

--------------------------------

### OptionStore - LDAP Server like objects

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Handles the management of LDAP server options and configurations within the fake LDAP environment, allowing for customization of mock server behavior.

```python
class OptionStore:
    pass
```

--------------------------------

### ObjectStore Loading Methods

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/objectstore.rst

Details the methods available on the ObjectStore class for loading LDAP objects. These include registering single objects, lists of objects, or loading objects from a JSON file.

```python
ObjectStore.register_object
ObjectStore.register_objects
ObjectStore.load_objects
```

--------------------------------

### Redhat Directory Server/389 Implementation Support

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Enables tests to simulate interactions with a Redhat Directory Server/389 implementation.

```APIDOC
Supports behavior for Redhat Directory Server/389 implementation.
```

--------------------------------

### LDAPFakerMixin for Unit Tests

Source: https://github.com/caltechads/python-ldap-faker/blob/master/README.md

Demonstrates the usage of LDAPFakerMixin, a helper class for unittest.TestCase. It automates the patching of python-ldap, allows populating LDAP servers with fixture data, and provides test instrumentation for inspecting state.

```python
class MyLDAPTests(unittest.TestCase):
    def setUp(self):
        self.addCleanup(LDAPFakerMixin.tearDown)
        self.ldap_faker = LDAPFakerMixin()
        self.ldap_faker.setUp()

    # ... your test methods using fake LDAP ...

    def test_search(self):
        # Example: Populate fake server and perform a search
        self.ldap_faker.add_objects('ldap://localhost:10389', [{'dn': 'cn=user,dc=example,dc=com', 'attributes': {'cn': ['user']}}])
        conn = ldap.initialize('ldap://localhost:10389')
        results = conn.search_s('dc=example,dc=com', ldap.SCOPE_WHOLE_SUBTREE, '(objectClass=*)')
        self.assertEqual(len(results), 1)

```

--------------------------------

### Run Tests for python-ldap-faker

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Executes the unit tests for the python-ldap-faker package.

```bash
python -m unittest discover
```

--------------------------------

### Registering a pre_set hook

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Demonstrates how to register a hook that executes before an object is saved in ObjectStore. The hook receives the store, the record, and the bind DN.

```python
from ldap_faker import hooks, ObjectStore, LDAPRecord


def pre_set_do_something_special(store: ObjectStore, record: LDAPRecord, bind_dn: str = None) -> None:
    pass

hooks.register('pre_set', pre_set_do_something_special)
```

--------------------------------

### Object Loading Callbacks - Python

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines callback functions for object loading in ObjectStore. pre_load_objects is called before loading a file, and post_load_objects is called after loading objects from a file. Both receive the ObjectStore and relevant data.

```APIDOC
pre_load_objects
    Signature: Callable[[store: ObjectStore, filename: str], None]

    Where store is the ObjectStore object and filename is the name of the data file to load.

    This will be executed on ObjectStore.load_objects before the file gets loaded.

post_load_objects
    Signature: Callable[[store: ObjectStore, records: List[LDAPRecord]], None]

    Where store is the ObjectStore object and records are the records that were loaded from the file.

    This will be executed on ObjectStore.load_objects after the objects loaded from the file get saved.
```

--------------------------------

### Configure ObjectStore for Redhat Directory Server/389

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/implementations.rst

Demonstrates how to initialize the ObjectStore with the '389' tag to enable Redhat Directory Server/389 specific behaviors.

```python
from ldap_faker import ObjectStore

store = ObjectStore(tags=['389'])
```

--------------------------------

### LDAP Object Create Callbacks

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines pre and post callback functions for the ObjectStore.create operation. These callbacks allow custom logic to be executed before or after an LDAP object is created.

```python
pre_create
    Signature: Callable[[store: ObjectStore, dn: str, modlist: AddModlist, bind_dn: str = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``dn`` is the record
    to be created, ``modlist`` is modlist to be used for creating the record, 
    and ``bind_dn`` is the dn of the user doing the ``create`` (possibly 
    ``None``).

    This will be executed on :py:meth:`ObjectStore.create` before the modlist
    gets processed.

    :py:meth:`ObjectStore.create` is what actually does the work when
    :py:meth:`FakeLDAPObject.add_s` is called.

post_create
    Signature: Callable[[store: ObjectStore, record: LDAPRecord, bind_dn: Optional[str] = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``record`` is the
    record to be created, and ``bind_dn`` is the dn of the user doing the 
    ``create`` (possibly ``None``).

    This will be executed on :py:meth:`ObjectStore.create` after the modlist has
    processed to build the object, but before it has been writen to the data store.
```

--------------------------------

### Run Tests

Source: https://github.com/caltechads/python-ldap-faker/blob/master/README.md

Executes the unit tests for the python-ldap-faker library. This command is useful for verifying the library's functionality or for developers contributing to the project.

```shell
python -m unittest discover
```

--------------------------------

### LDAPFakerMixin for unittest.TestCase

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Provides a mixin for unittest.TestCase to automatically manage python-ldap patching, load fixtures, and offer test instrumentation.

```APIDOC
LDAPFakerMixin:
  - Mixin for unittest.TestCase.
  - Automatically patches ldap.initialize, ldap.set_option, ldap.get_option.
  - Loads fixtures from JSON files.
  - Provides access to object store, connections, call history, and options.
  - Offers LDAP-specific asserts.
```

--------------------------------

### Root DSE Advertisement

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/controls.rst

Demonstrates how to query the Root DSE to check for supported LDAP controls, specifically showing the presence of the VLV OID.

```python
import ldap

rdata = conn.search_s(
    "",
    ldap.SCOPE_BASE,
    "(objectClass=*)",
    attrlist=["supportedControl"]
)

# Example: VLV OID will be present in supportedControl
vlv_oid = b"2.16.840.1.113730.3.4.9"
```

--------------------------------

### Server Side Sort with VLV Control for Search

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/controls.rst

Illustrates how to combine Server Side Sort and VLV controls for performing a sorted and paginated LDAP search.

```python
# Sort control is required for VLV
sort_control = LDAPControl('1.2.840.113556.1.4.473', True, encoded_sort_value)

# VLV control for pagination
vlv_control = LDAPControl(
    '2.16.840.1.113730.3.4.9',
    True,
    "1,1,5".encode('utf-8')  # 1 before, 1 after, target position 5
)

# Perform sorted VLV search
msgid = conn.search_ext(
    'ou=users,dc=example,dc=com',
    ldap.SCOPE_SUBTREE,
    '(objectClass=person)',
    serverctrls=[sort_control, vlv_control]
)
```

--------------------------------

### Object Registration Callbacks - Python

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines callback functions for object registration in ObjectStore. pre_register_objects is called before saving, and post_register_objects is called after saving. Both receive the ObjectStore and a list of LDAPRecord.

```APIDOC
pre_register_objects
    Signature: Callable[[store: ObjectStore, records: List[LDAPRecord]], None]

    Where store is the ObjectStore object and records is the list of records to be registered.

    This will be executed on ObjectStore.register_objects before the objects actually get saved.

post_register_objects
    Signature: Callable[[store: ObjectStore, records: List[LDAPRecord]], None]

    Where store is the ObjectStore object and records are the records that were registered.

    This will be executed on ObjectStore.register_objects after the objects get saved.
```

--------------------------------

### LDAP Object Set Callbacks

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines pre and post callback functions for the ObjectStore.set operation. These callbacks allow custom logic to be executed before or after an LDAP object is saved.

```python
post_set
    Signature: Callable[[store: ObjectStore, record: LDAPRecord, bind_dn: Optional[str] = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``record`` is the
    record to be ``set`` and ``bind_dn`` is the dn of the user doing the ``set``
    (possibly ``None``).

    This will be executed on :py:meth:`ObjectStore.set` after the object
    gets saved.
```

--------------------------------

### LDAPFakerMixin - Unittest Support

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Provides a mixin for unittest integration with python-ldap-faker, likely offering methods for setting up and tearing down fake LDAP environments during tests.

```python
class LDAPFakerMixin:
    pass
```

--------------------------------

### LDAP Object Registration Callbacks

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines pre and post callback functions for the ObjectStore.register_object operation. These callbacks allow custom logic to be executed before or after an LDAP object is registered.

```python
pre_register_object
    Signature: Callable[[store: ObjectStore, record: LDAPRecord], None]

    Where ``store`` is the :py:class:`ObjectStore` object and ``record`` is the
    record to be registered.

    This will be executed on :py:meth:`ObjectStore.register_object` before the object
    actually gets saved.

post_register_object
    Signature: Callable[[store: ObjectStore, record: LDAPRecord], None]

    Where ``store`` is the :py:class:`ObjectStore` object and ``record`` is the
    record that was registered.
```

--------------------------------

### LDAP Object Copy Callbacks

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines pre and post callback functions for the ObjectStore.copy operation. These callbacks allow custom logic to be executed before or after an LDAP object is copied.

```python
pre_copy
    Signature: Callable[[store: ObjectStore, dn: str], None]

    Where ``store`` is the :py:class:`ObjectStore` object, and ``dn`` is the
    DN of the object to copy.

    This will be executed on :py:meth:`ObjectStore.copy` before the object
    actually gets retrieved from the store to be copied.

post_copy
    Signature: Callable[[store: ObjectStore, data: LDAPData], LDAPData]

    Where ``store`` is the :py:class:`ObjectStore` object, and ``dn`` is the
    DN of the object to copy.  It should return the modified ``LDAPData`` dict.

    This will be executed on :py:meth:`ObjectStore.copy` after the object is
    retrieved from the store and :py:func:``copy.deepcopy`` has run, but before
    returning the data to the caller.
```

--------------------------------

### LDAP Call History and Server Simulation

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Describes the ability to inspect call history, simulate multiple fake LDAP servers, and manage test isolation.

```APIDOC
Inspect call history (name, arguments, order).
Simulate multiple fake LDAP servers with different object sets.
Test isolation: resets object store, connections, call history, and option changes between tests.
```

--------------------------------

### ObjectStore - LDAP Server like objects

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Manages the storage and retrieval of LDAP objects within a fake LDAP server environment, likely handling the data persistence for mock operations.

```python
class ObjectStore:
    pass
```

--------------------------------

### LDAPFakerMixin with Tagged Server Configuration

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/implementations.rst

Shows how to apply the '389' tag to LDAPFakerMixin for a single, default server or a named server in test cases.

```python
import unittest
from ldap_faker import LDAPFakerMixin


class TestDefaultTaggedServer(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp']
    ldap_fixtures = ('data.json', ['389'])
```

```python
import unittest
from ldap_faker import LDAPFakerMixin


class TestDefaultTaggedServer(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp']
    ldap_fixtures = [
        ('server1.json', 'ldap://server1', ['389']),
    ]
```

--------------------------------

### Authenticated Bind and ObjectStore Configuration

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/binds.rst

Explains how to perform an authenticated bind by loading a user object into the ObjectStore. It details the expected structure of the object, including the user's DN and password.

```python
(
    'uid=foo,ou=bar,o=baz,c=country',
    {
        "userPassword": [b"the password"],
    }
  )
```

--------------------------------

### LDAP Faker Mixin Test Case

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

A unittest TestCase demonstrating the use of LDAPFakerMixin for testing LDAP authentication and connection options. It mocks LDAP operations and asserts method calls.

```python
import unittest

import ldap
from ldap_faker import LDAPFakerMixin

from myapp import App

class YourTestCase(LDAPFakerMixin, unittest.TestCase):

    ldap_modules = ['myapp']
    ldap_fixtures = 'data.json'

    def test_auth_works(self):
        app = App()
        # A method that does a `simple_bind_s`
        app.auth('fred', 'the fredpassword')
        conn = self.get_connections()[0]
        self.assertLDAPConnectionMethodCalled(
            conn, 'simple_bind_s',
            {'who': 'uid=fred,ou=bar,o=baz,c=country', 'cred': 'the fredpassword'}
        )

    def test_correct_connection_options_were_set(self):
        app = App()
        app.auth('fred', 'the fredpassword')
        conn = self.get_connections()[0]
        self.assertLDAPConnectionOptionSet(conn, ldap.OPT_X_TLX_NEWCTX, 0)

    def test_tls_was_used_before_auth(self):
        app = App()
        app.auth('fred', 'the fredpassword')
        conn = self.get_connections()[0]
        self.assertLDAPConnectiontMethodCalled(conn, 'start_tls_s')
        self.assertLDAPConnectionMethodCalledAfter(conn, 'simple_bind_s', 'start_tls_s')
```

--------------------------------

### Faked python-ldap Functions

Source: https://github.com/caltechads/python-ldap-faker/blob/master/README.md

Lists the global functions from the python-ldap library that are faked by python-ldap-faker. These are the functions that will be replaced with mock implementations during testing.

```python
ldap.initialize
ldap.set_option
ldap.get_option
```

--------------------------------

### Faked python-ldap Global Functions

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Lists the global functions from the python-ldap library that are faked by python-ldap-faker.

```APIDOC
ldap.initialize
ldap.set_option
ldap.get_option
```

--------------------------------

### FakeLDAP - python-ldap Replacements

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

A fake implementation of the python-ldap library, designed to mock LDAP server interactions for testing purposes. It likely provides methods that mimic the standard python-ldap API.

```python
class FakeLDAP:
    pass
```

--------------------------------

### Server Side Sort Control Configuration

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/controls.rst

Demonstrates how to configure the Server Side Sort control for ascending or descending order sorting based on attribute type.

```python
sort_key_list.setComponentByPosition(1, uid_key)

encoded_value = encoder.encode(sort_key_list)
sort_control = LDAPControl('1.2.840.113556.1.4.473', True, encoded_value)
```

```python
# Sort by cn in descending order
sort_key = SortKey()
sort_key.setComponentByName("attributeType", "cn")
sort_key.setComponentByName("reverseOrder", True)
```

--------------------------------

### HookRegistry - Hook management

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Manages the registration, retrieval, and execution of hooks, providing an interface for interacting with the hook system.

```python
class HookRegistry:
    pass
```

--------------------------------

### Faked ldap.ldapobject.LDAPObject Methods

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Lists the methods of the ldap.ldapobject.LDAPObject class that are faked by python-ldap-faker.

```APIDOC
set_option
get_option
start_tls_s
simple_bind_s
unbind_s
search_s
search_ext
result3
compare_s
add_s
modify_s
rename_s
delete_s
modrdn_s
```

--------------------------------

### HookDefinition - Hook management

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Defines the structure and behavior of a hook, likely specifying the conditions under which it should be triggered and the actions it should perform.

```python
class HookDefinition:
    pass
```

--------------------------------

### LDAP Object Update Callbacks

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines pre and post callback functions for the ObjectStore.update operation. These callbacks allow custom logic to be executed before or after an LDAP object is modified.

```python
pre_update
    Signature: Callable[[store: ObjectStore, dn: str, modlist: Modlist, bind_dn: str = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``dn`` is the
    record to be modified`, ``modlist`` is modlist to be applied to the record, 
    and ``bind_dn`` is the dn of the user doing the ``update`` (possibly ``None``).

    This will be executed on :py:meth:`ObjectStore.update` before the object
    actually gets saved.

    :py:meth:`ObjectStore.update` is what actually does the work when
    :py:meth:`FakeLDAPObject.modify_s` is called.

post_update
    Signature: Callable[[store: ObjectStore, record: LDAPRecord, bind_dn: Optional[str] = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``record`` is the
    updated record and ``bind_dn`` is the dn of the user doing the ``update``
    (possibly ``None``)

    This will be executed on :py:meth:`ObjectStore.update` after the modlist has
    been applied to the object, but before it has been writen to the data store.
```

--------------------------------

### Faked LDAPObject Methods

Source: https://github.com/caltechads/python-ldap-faker/blob/master/README.md

Lists the methods of the ldap.ldapobject.LDAPObject class that are faked by python-ldap-faker. These methods provide the core LDAP operations that are simulated for testing purposes.

```python
set_option
get_option
start_tls_s
simple_bind_s
unbind_s
search_s
search_ext
result3
compare_s
add_s
modify_s
rename_s
delete_s
```

--------------------------------

### LDAP Filter and Search Features

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/index.rst

Details the advanced search capabilities including filter validation, Paged Results, and server-side sorting.

```APIDOC
search_ext and search_s:
  - Validates LDAP filter strings.
  - Applies filters directly to fake server objects.
  - Supports Paged Results (OID 1.2.840.113556.1.4.319).
  - Supports server-side sorting (OID 1.2.840.113556.1.4.473).
  - Supports Virtual List View (VLV) control (OID 2.16.840.1.113730.3.4.9) for pagination.
```

--------------------------------

### FakeLDAP Instance Attributes

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/unittest.rst

Details the attributes available on the FakeLDAP instance provided to each test method. These include connections, options, and call histories, allowing for detailed inspection of LDAP interactions during testing.

```python
LDAPFakerMixin.fake_ldap

# Attributes of FakeLDAP instance:
# FakeLDAP.connections: List of FakeLDAPObject connections
# FakeLDAP.options: OptionStore object for global LDAP options
# FakeLDAP.calls: CallHistory object for calls to initialize, set_option, get_option
```

--------------------------------

### LDAP Object Delete Callbacks

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/hooks.rst

Defines pre and post callback functions for the ObjectStore.delete operation. These callbacks allow custom logic to be executed before or after an LDAP object is deleted.

```python
pre_delete
    Signature: Callable[[store: ObjectStore, record: LDAPRecord, bind_dn: Optional[str] = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``record`` is the
    record to deleted, and ``bind_dn`` is the dn of the user doing the ``set``
    (possibly ``None``).

    This will be executed on :py:meth:`ObjectStore.delete` before the object
    actually gets deleted from the data store.

    :py:meth:`ObjectStore.delete` is what actually does the work when
    :py:meth:`FakeLDAPObject.delete_s` is called, and is also called
    during :py:meth:`FakeLDAPObject.rename_s` to delete the old object.

post_delete
    Signature: Callable[[store: ObjectStore, record: LDAPRecord, bind_dn: Optional[str] = None], None]

    Where ``store`` is the :py:class:`ObjectStore` object, ``record`` is the
    record deleted, and ``bind_dn`` is the dn of the user doing the ``set``
    (possibly ``None``).

    This will be executed on :py:meth:`ObjectStore.delete` after the object
    actually gets deleted from the data store.
```

--------------------------------

### FakeLDAPObject Attributes

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/unittest.rst

Describes the attributes of FakeLDAPObject instances, which represent individual LDAP connections. These attributes provide information about the LDAP URI, data store, connection-specific options, API calls made, and binding status.

```python
# Attributes of FakeLDAPObject instances:
# FakeLDAPObject.uri: LDAP URI requested
# FakeLDAPObject.store: ObjectStore copy of data
# FakeLDAPObject.options: OptionStore for connection-specific options
# FakeLDAPObject.calls: CallHistory for python-ldap API calls to this object
# FakeLDAPObject.bound_dn: DN used for simple_bind_s, or None for anonymous binding
# FakeLDAPObject.tls_enabled: True if start_tls_s was used
```

--------------------------------

### hooks - Hook management

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

A global variable or object representing the hook registry, used for managing and accessing custom hooks within the python-ldap-faker library.

```python
hooks = ... # Represents the hook registry
```

--------------------------------

### CallHistory - Unittest Support

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Manages a collection of LDAPCallRecord objects, providing an interface to access and analyze the history of LDAP calls made within a test.

```python
class CallHistory:
    pass
```

--------------------------------

### Case-Insensitive LDAP Operations

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/objectstore.rst

Illustrates the case-insensitive nature of LDAP distinguished names (dn) and basedn in python-ldap-faker, as well as case-insensitive attribute and value comparisons during searches.

```python
ldap_obj.simple_bind_s("uid=foo,ou=bar,o=baz,c=country", "the password")
ldap_obj.simple_bind_s("UID=FOO,OU=BAR,O=BAZ,C=COUNTRY", "the password")

ldap_obj.search_s("ou=bar,o=baz,c=country", ldap.SCOPE_SUBTREE, '(uid=bar)')
ldap_obj.search_s("ou=bar,o=baz,c=country", ldap.SCOPE_SUBTREE, '(UID=bar)')
ldap_obj.search_s("ou=bar,o=baz,c=country", ldap.SCOPE_SUBTREE, '(uid=bAr)')
```

--------------------------------

### LDAP Record Structure

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/objectstore.rst

Describes the structure of LDAP objects as represented by python-ldap-faker. LDAP objects consist of a distinguished name (dn) and a dictionary of attributes, where attribute names are strings and attribute values are lists of bytes.

```python
(
    'uid=user,ou=mydept,o=myorg,c=country',
    {
        'cn': [b'Firstname User1'],
        'uid': [b'user'],
        'uidNumber': [b'123'],
        'gidNumber': [b'456'],
        'homeDirectory': [b'/home/user'],
        'loginShell': [b'/bin/bash'],
        'userPassword': [b'the password'],
        'objectclass': [b'posixAccount', b'top']
    }
)
```

--------------------------------

### LDAPCallRecord - Unittest Support

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Represents a record of an LDAP call made during testing, likely used to inspect and assert the behavior of mocked LDAP operations.

```python
class LDAPCallRecord:
    pass
```

--------------------------------

### LDAPFixtureList - Type Aliases

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Type alias for a list of LDAP fixtures, likely used for setting up predefined LDAP data for testing.

```python
LDAPFixtureList = ... # Type alias for a list of LDAP fixtures
```

--------------------------------

### Hook - Hook management

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Represents a single hook, likely defining a mechanism for intercepting or modifying LDAP operations.

```python
class Hook:
    pass
```

--------------------------------

### FakeLDAPObject - python-ldap Replacements

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Represents a fake LDAP object, likely used in conjunction with FakeLDAP to simulate individual entries or search results from an LDAP server.

```python
class FakeLDAPObject:
    pass
```

--------------------------------

### LDAPOptionValue - Type Aliases

Source: https://github.com/caltechads/python-ldap-faker/blob/master/doc/source/api.rst

Type alias for LDAP option values, used for type hinting and improving code readability when dealing with LDAP configurations.

```python
LDAPOptionValue = ... # Type alias for LDAP option values
```