(important)

all CookieJar methods below are not related to file storage, should go to Cookie or module level functions

_match_path and _match_domain are used by get_header to help search cookies when walking through the <domain>/<path>/<name> tree. They're not related to cookie directly, since at that moment no cookie is get. And they are only used in CookieJar. I think it makes sense to place them in CookieJar as private methods.

get_header is out of scope file storage (CookieJar) too. Imagine SqliteCookieJar, it needs all these methods but it definitely must not couple with private methods of file storage (CookieJar).

Sorry, I still didn't get your point about this change.

The httplib2.CookieJar is not a file storage. It's a cookie jar in memory with functions to load cookies from/or save to file. Just like get()/set()/clear(), the get_header() is not special, it means getting the cookies in the format of HTTP header. Similarly, extract_header means setting the cookies from HTTP header.

Maybe it will be much clear if separating the FileCookieJar from the CookieJar. For example:

class CookieJarBase(CookieJar):
       <null operations>
 
NullCookieJar = CookieJarBase

class CookieJar(CookieJarBase):
        1. Virtual interfaces to persist the cookies: load()/save() 
        2. Implement all other operations(also includes `get_header`/`extract_header`) on self._cookies

class FileCookieJar(CookieJar):
        Re-implement save()/load() interface with file storage

class SqliteCookieJar(CookieJar):  <-- your example
        Re-implement save()/load() interface with sqlite database

The word "jar" means storage for cookies. So CookieJar should contain code that is related to storing cookies: in memory, file or somewhere else. get_header, extract_header are helper functions that are not related to storage.

It's very fine and clear for some functions to be at module level. There is no need to implement Java style class hierarchy. That virtual/implement/override nightmare is part of what made Python stdlib HTTP client so hard to use in the first place. Because you can't clearly read code: you start reading a method, it calls something in parent, look there, which calls something not in parent, look back, it's very easy for machine, but we should care about people.

If you want to separate cookie access and storage, it's a great idea but additional work. Because right now, each set() writing to disk is a performance problem.

class CookieJar(object):
  """Cookie in-memory storage"""
  def __init__(self):
    self._items = {}
  def get/set/clear():  # the cookie access methods only
  def __hash__():  # to help storage know when contents were modified and should be written to disk/db/etc

# not related to any storage or cookie access
def get_header():
def extract_header():

# and then separate storage, named as json and all other serialization APIs
def load(fileobj) -> CookieJar:
def dump(fileobj, CookieJar):

# this way, new database backend would only implement load/dump

Variant of your code with base jar is also fine:

class NullCookieJar(object):
  def get/set/clear(): ...
  # no load/save/get_header


class MemoryCookieJar(object):
  def get/set/clear(): ...
  # no load/save/get_header


# inherit MemoryCookieJar only as API convenience, no virtual/override methods
class FileCookieJar(MemoryCookieJar):
  def load/save(): ...
  # no get/set/clear/get_header


class SqliteCookieJar(object):
  def get() -> db.SELECT
  def set() -> db.INSERT/UPDATE
  def clear() -> db.DELETE
  # no load/save/get_header


class BatchSqliteCookieJar(MemoryCookieJar):
  def load() -> db.SELECT
  def save() -> db.INSERT/UPDATE
  # no get/set/clear/get_header

Please let me try to explain the issue here from another point.

CookieJar is public API, in sense that new storage backend must implement some methods for everything to work. So we must document what is the API (or at least provide refence implementation that other people may copy/modify). So what's the CookieJar API? You say it includes get_header/extract_header. It's even visible in that NullCookieJar implements get_header (which is wrong). Now somebody needs to store cookies in database. It completely makes sense that they must create get/set/clear, right?

class DatabaseCookieJar(object):
  def get/set/clear(): ... # makes sense

but it doesn't work, because Http._set_cookie_header calls your jar get_header. And they think, what my database cookie jar implementation must do differently in get_header? Ah there is (and could be) no new behavior (mind alarm 1). So what are their options?

# option 1
class DatabaseCookieJar(object):
  def get/set/clear(): ...

  @staticmethod
  def get_header(*a, **kw): return CookieJar.get_header(*a, **kw)

# option 2
class DatabaseCookieJar(CookieJar):  # why? only to make _set_cookie_header happy
  def get/set/clear(): ...

And they think, why my database implementation must couple with file cookie storage? There is no good reason. Because _set_cookie_header calls some common helper function via .cookie_jar property.

And yet another point: one may want to construct/parse cookie headers without knowing about file/memory/database cookie storage. Right?

Variant of your code with base jar is also fine:

class NullCookieJar(object):
  def get/set/clear(): ...
  # no load/save/get_header


class MemoryCookieJar(object):
  def get/set/clear(): ...
  # no load/save/get_header


# inherit MemoryCookieJar only as API convenience, no virtual/override methods
class FileCookieJar(MemoryCookieJar):
  def load/save(): ...
  # no get/set/clear/get_header


class SqliteCookieJar(object):
  def get() -> db.SELECT
  def set() -> db.INSERT/UPDATE
  def clear() -> db.DELETE
  # no load/save/get_header


class BatchSqliteCookieJar(MemoryCookieJar):
  def load() -> db.SELECT
  def save() -> db.INSERT/UPDATE
  # no get/set/clear/get_header

Without the load/save virtual interface in MemoryCookieJar, you cannot keep updating the file/sqldatabse on each set/clear operation in the FileCookieJar/BatchSqliteCookieJar

Yes, you can do like getattr(http.cookie_jar, 'save', lambda: None)() but that is ugly.