docs: def connection(self, shareable=True):
          """Get a steady, cached DB-API 2 connection from the pool.
  
          If shareable is set and the underlying DB-API 2 allows it,
          then the connection may be shared with other threads.
  
          """
          if shareable and self._maxshared:
              self._lock.acquire()
              try:
                  while (not self._shared_cache and self._maxconnections
                          and self._connections >= self._maxconnections):
                      self._wait_lock()
                  if len(self._shared_cache) < self._maxshared:
                      # shared cache is not full, get a dedicated connection
                      try:  # first try to get it from the idle cache
                          con = self._idle_cache.pop(0)
                      except IndexError:  # else get a fresh connection
                          con = self.steady_connection()
                      else:
                          con._ping_check()  # check this connection
                      con = SharedDBConnection(con)
                      self._connections += 1
                  else:  # shared cache full or no more connections allowed
                      self._shared_cache.sort()  # least shared connection first
                      con = self._shared_cache.pop(0)  # get it
                      while con.con._transaction:
                          # do not share connections which are in a transaction
                          self._shared_cache.insert(0, con)
                          self._wait_lock()
                          self._shared_cache.sort()
                          con = self._shared_cache.pop(0)
                      con.con._ping_check()  # check the underlying connection
                      con.share()  # increase share of this connection
                  # put the connection (back) into the shared cache
                  self._shared_cache.append(con)
                  self._lock.notify()
              finally:
                  self._lock.release()
              con = PooledSharedDBConnection(self, con)
          else:  # try to get a dedicated connection
              self._lock.acquire()
              try:
                  while (self._maxconnections
                          and self._connections >= self._maxconnections):
                      self._wait_lock()
                  # connection limit not reached, get a dedicated connection
                  try:  # first try to get it from the idle cache
                      con = self._idle_cache.pop(0)
                  except IndexError:  # else get a fresh connection
                      con = self.steady_connection()
                  else:
                      con._ping_check()  # check connection
                  con = PooledDedicatedDBConnection(self, con)
                  self._connections += 1
              finally:
                  self._lock.release()
          return con