Dataset doesn't seem to have the right return types for a lot of its methods. As a very basic example, consider opening a table:

db = dataset.connect()
user_table = db['user']

Based on the documentation, this is intended to either get a reference to an existing table or to create a new table if there isn't a user table. However, this is consistently flagged by my type checker (PyLance) as possibly being None, which also causes problems for autocomplete.

Accessing a table as above calls dataset.Database.__getitem__, which dispatches to either dataset.Table.create_table or dataset.Table.load_table. These are both quite similar; here's the body of load_table:

        table_name = normalize_table_name(table_name)
        with self.lock:
            if table_name not in self._tables:
                self._tables[table_name] = Table(self, table_name)
            return self._tables.get(table_name)

This first checks if self._tables contains table_name and adds a new Table if it doesn't, so self.tables should always contain table_name. Despite this, the final return statement has a call to self._tables.get(table_name), which would return None if the table_name were not present. The type checker doesn't pick this up, so load_table has a return type of typing.Optional[dataset.Table] rather than dataset.Table, even though it should never return None. As a consequence, autocomplete doesn't really work correctly, because the useful methods of dataset.Table aren't present for None.

I'd be happy to clean things up a bit to eliminate this sort of incorrect typing of methods. Before I start on that, though, I'd like to make sure I'm not missing anything about why self._tables.get(table_name) is used instead of self._tables[table_name].