Update docs for extra attributes

docs/tutorial/using-files-in-models.md

@@ -132,8 +132,59 @@ the default attributes used by [File][sqlalchemy_file.file.File] object internal
     [File][sqlalchemy_file.file.File] provides also attribute style access. 
     You can access your keys as attributes.
 
+### Extra & Headers
+
+`Apache-libcloud` allow you to store each object with some `extra` attributes or additional `headers`. 
+
+They are two ways to add `extra` and `headers` with *sqlalchemy-file*
+
+- on field declaration (shared by all associated files)
+
+```python
+
+class Attachment(Base):
+    __tablename__ = "attachment"
+
+    id = Column(Integer, autoincrement=True, primary_key=True)
+    name = Column(String(50), unique=True)
+    content = Column(
+        FileField(
+            extra={
+                "acl": "private",
+                "dummy_key": "dummy_value",
+                "meta_data": {"key1": "value1", "key2": "value2"},
+            },
+            headers={
+                "Access-Control-Allow-Origin": "http://test.com",
+                "Custom-Key": "xxxxxxx",
+            },
+        )
+    )
+
+```
+
+- in your [File][sqlalchemy_file.file.File] object
+
+!!! important
+    When the Field has default `extra` attribute, it's overridden by [File][sqlalchemy_file.file.File] object `extra`
+    attribute
+```python hl_lines="4"
+with Session(engine) as session:
+    attachment = Attachment(
+            name="Public document",
+            content=File(DummyFile(), extra={"acl": "public-read"}),
+        )
+    session.add(attachment)
+    session.commit()
+    session.refresh(attachment)
+
+    assert attachment.content.file.object.extra["acl"] == "public-read"
+```
 ### Metadata
 
+!!! warning
+    This attribute is now deprecated, migrate to [extra](#extra-headers)
+
 *SQLAlchemy-file* store the uploaded file with some metadata. Only `filename` and `content_type` are sent by default,
 . You can complete with `metadata` key inside your [File][sqlalchemy_file.file.File] object.
 
@@ -153,7 +204,7 @@ the default attributes used by [File][sqlalchemy_file.file.File] object internal
 
 ## Uploading on a Specific Storage
 
-By default all the files are uploaded on the default storage which is the first added storage. This can be changed
+By default, all the files are uploaded on the default storage which is the first added storage. This can be changed
 by passing a `upload_storage` argument explicitly on field declaration:
 
 ```Python

docs_src/tutorial/using-files-in-models/009_extra_and_headers.py

@@ -0,0 +1,25 @@
+from sqlalchemy import Column, Integer, String
+from sqlalchemy.orm import declarative_base
+from sqlalchemy_file.types import FileField
+
+Base = declarative_base()
+
+
+class Attachment(Base):
+    __tablename__ = "attachment"
+
+    id = Column(Integer, autoincrement=True, primary_key=True)
+    name = Column(String(50), unique=True)
+    content = Column(
+        FileField(
+            extra={
+                "acl": "private",
+                "dummy_key": "dummy_value",
+                "meta_data": {"key1": "value1", "key2": "value2"},
+            },
+            headers={
+                "Access-Control-Allow-Origin": "http://test.com",
+                "Custom-Key": "xxxxxxx",
+            },
+        )
+    )

scripts/format.sh

@@ -2,5 +2,5 @@
 
 set -e
 set -x
-ruff sqlalchemy_file tests --fix
+ruff sqlalchemy_file tests docs_src --fix
 black .

tests/test_extra_and_headers.py

@@ -12,22 +12,25 @@
 engine = get_test_engine()
 Base = declarative_base()
 
-EXTRA = {
-    "acl": "private",
-    "dummy_key": "dummy_value",
-    "meta_data": {"key1": "value1", "key2": "value2"},
-}
-
-HEADERS = {"Access-Control-Allow-Origin": "http://test.com", "X-KEY": "xxxxxxx"}
-
 
 class Attachment(Base):
     __tablename__ = "attachment"
 
     id = Column(Integer, autoincrement=True, primary_key=True)
     name = Column(String(50), unique=True)
-    content = Column(FileField())
-    content_with_extra = Column(FileField(extra=EXTRA, headers=HEADERS))
+    content = Column(
+        FileField(
+            extra={
+                "acl": "private",
+                "dummy_key": "dummy_value",
+                "meta_data": {"key1": "value1", "key2": "value2"},
+            },
+            headers={
+                "Access-Control-Allow-Origin": "http://test.com",
+                "Custom-Key": "xxxxxxx",
+            },
+        )
+    )
 
 
 @pytest.fixture
@@ -48,26 +51,22 @@ def session(engine: Engine) -> Session:
 
 
 def test_each_file_inherit_extra_from_field(session: Session):
-    attachment = Attachment(name="Protected document", content_with_extra=DummyFile())
+    attachment = Attachment(name="Protected document", content=DummyFile())
     session.add(attachment)
     session.commit()
     session.refresh(attachment)
-    assert attachment.content_with_extra.file.object.extra["acl"] == "private"
-    assert attachment.content_with_extra.file.object.extra["dummy_key"] == "dummy_value"
-    assert (
-        attachment.content_with_extra.file.object.extra["meta_data"]["key1"] == "value1"
-    )
-    assert (
-        attachment.content_with_extra.file.object.extra["meta_data"]["key2"] == "value2"
-    )
+    assert attachment.content.file.object.extra["acl"] == "private"
+    assert attachment.content.file.object.extra["dummy_key"] == "dummy_value"
+    assert attachment.content.file.object.extra["meta_data"]["key1"] == "value1"
+    assert attachment.content.file.object.extra["meta_data"]["key2"] == "value2"
 
 
 def test_overriding_default_extra(session: Session):
     attachment = Attachment(
         name="Public document",
-        content_with_extra=File(DummyFile(), extra={"acl": "public-read"}),
+        content=File(DummyFile(), extra={"acl": "public-read"}),
     )
     session.add(attachment)
     session.commit()
     session.refresh(attachment)
-    assert attachment.content_with_extra.file.object.extra["acl"] == "public-read"
+    assert attachment.content.file.object.extra["acl"] == "public-read"