# -*- coding: utf-8 -*-

# Copyright 2012 splinter authors. All rights reserved.

# Use of this source code is governed by a BSD-style

# license that can be found in the LICENSE file.

from splinter.meta import InheritedDocs

class CookieManagerAPI(InheritedDocs('_CookieManagerAPI', (object,), {})):

"""

An API that specifies how a splinter driver deals with cookies.

You can add cookies using the :meth:`add <CookieManagerAPI.add>` method,

and remove one or all cookies using

the :meth:`delete <CookieManagerAPI.delete>` method.

A CookieManager acts like a ``dict``, so you can access the value of a

cookie through the [] operator, passing the cookie identifier:

>>> cookie_manager.add({'name': 'Tony'})

>>> assert cookie_manager['name'] == 'Tony'

"""

def add(self, cookies):

"""

Adds a cookie.

The ``cookie`` parameter is a ``dict`` where each key is an identifier

for the cookie value (like any ``dict``).

Example of use:

>>> cookie_manager.add({'name': 'Tony'})

"""

raise NotImplementedError

def delete(self, *cookies):

"""

Deletes one or more cookies. You can pass all the cookies identifier

that you want to delete.

If none identifier is provided, all cookies are deleted.

Examples:

>>> cookie_manager.delete() # deletes all cookies

>>> cookie_manager.delete('name', 'birthday',

'favorite_color') # deletes these three cookies

>>> cookie_manager.delete('name') # deletes one cookie

"""

raise NotImplementedError

def all(self, verbose=False):

"""

Returns all of the cookies.

**Note:** If you're using any webdriver and want more info about

the cookie, set the `verbose` parameter to `True` (in other

drivers, it won't make any difference). In this case, this method

will return a list of dicts, each with one cookie's info.

Examples:

>>> cookie_manager.add({'name': 'Tony'})

>>> cookie_manager.all()

[{'name': 'Tony'}]

"""

raise NotImplementedError

def __getitem__(self, item):

raise NotImplementedError

def __eq__(self, other_object):

raise NotImplementedError