user: Show practical ways to work with ID(bpy_struct) in a Blender add-on or script – include code.

assistant: # ID(bpy_struct)

base class — [`bpy_struct`](bpy.types.bpy_struct.html#bpy.types.bpy_struct "bpy.types.bpy_struct")

subclasses —
[`Action`](bpy.types.Action.html#bpy.types.Action "bpy.types.Action"), [`Annotation`](bpy.types.Annotation.html#bpy.types.Annotation "bpy.types.Annotation"), [`Armature`](bpy.types.Armature.html#bpy.types.Armature "bpy.types.Armature"), [`Brush`](bpy.types.Brush.html#bpy.types.Brush "bpy.types.Brush"), [`CacheFile`](bpy.types.CacheFile.html#bpy.types.CacheFile "bpy.types.CacheFile"), [`Camera`](bpy.types.Camera.html#bpy.types.Camera "bpy.types.Camera"), [`Collection`](bpy.types.Collection.html#bpy.types.Collection "bpy.types.Collection"), [`Curve`](bpy.types.Curve.html#bpy.types.Curve "bpy.types.Curve"), [`Curves`](bpy.types.Curves.html#bpy.types.Curves "bpy.types.Curves"), [`FreestyleLineStyle`](bpy.types.FreestyleLineStyle.html#bpy.types.FreestyleLineStyle "bpy.types.FreestyleLineStyle"), [`GreasePencil`](bpy.types.GreasePencil.html#bpy.types.GreasePencil "bpy.types.GreasePencil"), [`Image`](bpy.types.Image.html#bpy.types.Image "bpy.types.Image"), [`Key`](bpy.types.Key.html#bpy.types.Key "bpy.types.Key"), [`Lattice`](bpy.types.Lattice.html#bpy.types.Lattice "bpy.types.Lattice"), [`Library`](bpy.types.Library.html#bpy.types.Library "bpy.types.Library"), [`Light`](bpy.types.Light.html#bpy.types.Light "bpy.types.Light"), [`LightProbe`](bpy.types.LightProbe.html#bpy.types.LightProbe "bpy.types.LightProbe"), [`Mask`](bpy.types.Mask.html#bpy.types.Mask "bpy.types.Mask"), [`Material`](bpy.types.Material.html#bpy.types.Material "bpy.types.Material"), [`Mesh`](bpy.types.Mesh.html#bpy.types.Mesh "bpy.types.Mesh"), [`MetaBall`](bpy.types.MetaBall.html#bpy.types.MetaBall "bpy.types.MetaBall"), [`MovieClip`](bpy.types.MovieClip.html#bpy.types.MovieClip "bpy.types.MovieClip"), [`NodeTree`](bpy.types.NodeTree.html#bpy.types.NodeTree "bpy.types.NodeTree"), [`Object`](bpy.types.Object.html#bpy.types.Object "bpy.types.Object"), [`PaintCurve`](bpy.types.PaintCurve.html#bpy.types.PaintCurve "bpy.types.PaintCurve"), [`Palette`](bpy.types.Palette.html#bpy.types.Palette "bpy.types.Palette"), [`ParticleSettings`](bpy.types.ParticleSettings.html#bpy.types.ParticleSettings "bpy.types.ParticleSettings"), [`PointCloud`](bpy.types.PointCloud.html#bpy.types.PointCloud "bpy.types.PointCloud"), [`Scene`](bpy.types.Scene.html#bpy.types.Scene "bpy.types.Scene"), [`Screen`](bpy.types.Screen.html#bpy.types.Screen "bpy.types.Screen"), [`Sound`](bpy.types.Sound.html#bpy.types.Sound "bpy.types.Sound"), [`Speaker`](bpy.types.Speaker.html#bpy.types.Speaker "bpy.types.Speaker"), [`Text`](bpy.types.Text.html#bpy.types.Text "bpy.types.Text"), [`Texture`](bpy.types.Texture.html#bpy.types.Texture "bpy.types.Texture"), [`VectorFont`](bpy.types.VectorFont.html#bpy.types.VectorFont "bpy.types.VectorFont"), [`Volume`](bpy.types.Volume.html#bpy.types.Volume "bpy.types.Volume"), [`WindowManager`](bpy.types.WindowManager.html#bpy.types.WindowManager "bpy.types.WindowManager"), [`WorkSpace`](bpy.types.WorkSpace.html#bpy.types.WorkSpace "bpy.types.WorkSpace"), [`World`](bpy.types.World.html#bpy.types.World "bpy.types.World")

*class* bpy.types.ID(*bpy_struct*)
:   Base type for data-blocks, defining a unique name, linking from other libraries and garbage collection

    asset_data
    :   Additional data for an asset data-block

        Type:
        :   [`AssetMetaData`](bpy.types.AssetMetaData.html#bpy.types.AssetMetaData "bpy.types.AssetMetaData")

    id_type
    :   Type identifier of this data-block

        Type:
        :   enum in [Id Type Items](bpy_types_enum_items/id_type_items.html#rna-enum-id-type-items), default `'ACTION'`, (readonly)

    is_editable
    :   This data-block is editable in the user interface. Linked data-blocks are not editable, except if they were loaded as editable assets.

        Type:
        :   boolean, default False, (readonly)

    is_embedded_data
    :   This data-block is not an independent one, but is actually a sub-data of another ID (typical example: root node trees or master collections)

        Type:
        :   boolean, default False, (readonly)

    is_evaluated
    :   Whether this ID is runtime-only, evaluated data-block, or actual data from .blend file

        Type:
        :   boolean, default False, (readonly)

    is_library_indirect
    :   Is this ID block linked indirectly

        Type:
        :   boolean, default False, (readonly)

    is_linked_packed
    :   This data-block is linked and packed into the .blend file

        Type:
        :   boolean, default False, (readonly)

    is_missing
    :   This data-block is a place-holder for missing linked data (i.e. it is [an override of] a linked data that could not be found anymore)

        Type:
        :   boolean, default False, (readonly)

    is_runtime_data
    :   This data-block is runtime data, i.e. it won’t be saved in .blend file. Note that e.g. evaluated IDs are always runtime, so this value is only editable for data-blocks in Main data-base.

        Type:
        :   boolean, default False

    library
    :   Library file the data-block is linked from

        Type:
        :   [`Library`](bpy.types.Library.html#bpy.types.Library "bpy.types.Library"), (readonly)

    library_weak_reference
    :   Weak reference to a data-block in another library .blend file (used to re-use already appended data instead of appending new copies)

        Type:
        :   [`LibraryWeakReference`](bpy.types.LibraryWeakReference.html#bpy.types.LibraryWeakReference "bpy.types.LibraryWeakReference"), (readonly)

    name
    :   Unique data-block ID name (within a same type and library)

        Type:
        :   string, default “”, (never None)

    name_full
    :   Unique data-block ID name, including library one if any

        Type:
        :   string, default “”, (readonly, never None)

    original
    :   Actual data-block from .blend file (Main database) that generated that evaluated one

        Type:
        :   [`ID`](#bpy.types.ID "bpy.types.ID"), (readonly)

    override_library
    :   Library override data

        Type:
        :   [`IDOverrideLibrary`](bpy.types.IDOverrideLibrary.html#bpy.types.IDOverrideLibrary "bpy.types.IDOverrideLibrary"), (readonly)

    preview
    :   Preview image and icon of this data-block (always None if not supported for this type of data)

        Type:
        :   [`ImagePreview`](bpy.types.ImagePreview.html#bpy.types.ImagePreview "bpy.types.ImagePreview"), (readonly)

    session_uid
    :   A session-wide unique identifier for the data block that remains the same across renames and internal reallocations, unchanged when reloading the file

        Type:
        :   int in [-inf, inf], default 0, (readonly)

    tag
    :   Tools can use this to tag data for their own purposes (initial state is undefined)

        Type:
        :   boolean, default False

    use_extra_user
    :   Indicates whether an extra user is set or not (mainly for internal/debug usages)

        Type:
        :   boolean, default False

    use_fake_user
    :   Save this data-block even if it has no users

        Type:
        :   boolean, default False

    users
    :   Number of times this data-block is referenced

        Type:
        :   int in [0, inf], default 0, (readonly)

    bl_system_properties_get(*\**, *do_create=False*)
    :   DEBUG ONLY. Internal access to runtime-defined RNA data storage, intended solely for testing and debugging purposes. Do not access it in regular scripting work, and in particular, do not assume that it contains writable data

        Parameters:
        :   **do_create** (*boolean**,* *(**optional**)*) – Ensure that system properties are created if they do not exist yet

        Returns:
        :   The system properties root container, or None if there are no system properties stored in this data yet, and its creation was not requested

        Return type:
        :   [`PropertyGroup`](bpy.types.PropertyGroup.html#bpy.types.PropertyGroup "bpy.types.PropertyGroup")

    rename(*name*, *\**, *mode='NEVER'*)
    :   More refined handling in case the new name collides with another ID’s name

        Parameters:
        :   - **name** (*string**,* *(**never None**)*) – New name to rename the ID to, if empty will re-use the current ID name
            - **mode** (enum in [`'NEVER'`, `'ALWAYS'`, `'SAME_ROOT'`], (optional)) –

              How to handle name collision, in case the requested new name is already used by another ID of the same type

              - `NEVER`
                Never Rename – Never rename an existing ID whose name would conflict, the currently renamed ID will get a numeric suffix appended to its new name.
              - `ALWAYS`
                Always Rename – Always rename an existing ID whose name would conflict, ensuring that the currently renamed ID will get requested name.
              - `SAME_ROOT`
                Rename If Same Root – Only rename an existing ID whose name would conflict if its name root (everything besides the numerical suffix) is the same as the existing name of the currently renamed ID.

        Returns:
        :   How did the renaming of the data-block went on

            - `UNCHANGED`
              Unchanged – The ID was not renamed, e.g. because it is already named as requested.
            - `UNCHANGED_COLLISION`
              Unchanged Due to Collision – The ID was not renamed, because requested name would have collided with another existing ID’s name, and the automatically adjusted name was the same as the current ID’s name.
            - `RENAMED_NO_COLLISION`
              Renamed Without Collision – The ID was renamed as requested, without creating any name collision.
            - `RENAMED_COLLISION_ADJUSTED`
              Renamed With Collision – The ID was renamed with adjustment of the requested name, to avoid a name collision.
            - `RENAMED_COLLISION_FORCED`
              Renamed Enforced With Collision – The ID was renamed as requested, also renaming another ID to avoid a name collision.

        Return type:
        :   enum in [`'UNCHANGED'`, `'UNCHANGED_COLLISION'`, `'RENAMED_NO_COLLISION'`, `'RENAMED_COLLISION_ADJUSTED'`, `'RENAMED_COLLISION_FORCED'`]

    evaluated_get(*depsgraph*)
    :   Get corresponding evaluated ID from the given dependency graph. Note that this does not ensure the dependency graph is fully evaluated, it just returns the result of the last evaluation.

        Parameters:
        :   **depsgraph** ([`Depsgraph`](bpy.types.Depsgraph.html#bpy.types.Depsgraph "bpy.types.Depsgraph"), (never None)) – Dependency graph to perform lookup in

        Returns:
        :   New copy of the ID

        Return type:
        :   [`ID`](#bpy.types.ID "bpy.types.ID")

    copy()
    :   Create a copy of this data-block (not supported for all data-blocks). The result is added to the Blend-File Data (Main database), with all references to other data-blocks ensured to be from within the same Blend-File Data.

        Returns:
        :   New copy of the ID

        Return type:
        :   [`ID`](#bpy.types.ID "bpy.types.ID")

    asset_mark()
    :   Enable easier reuse of the data-block through the Asset Browser, with the help of customizable metadata (like previews, descriptions and tags)

    asset_clear()
    :   Delete all asset metadata and turn the asset data-block back into a normal data-block

    asset_generate_preview()
    :   Generate preview image (might be scheduled in a background thread)

    override_create(*\**, *remap_local_usages=False*)
    :   Create an overridden local copy of this linked data-block (not supported for all data-blocks)

        Parameters:
        :   **remap_local_usages** (*boolean**,* *(**optional**)*) – Whether local usages of the linked ID should be remapped to the new library override of it

        Returns:
        :   New overridden local copy of the ID

        Return type:
        :   [`ID`](#bpy.types.ID "bpy.types.ID")

    override_hierarchy_create(*scene*, *view_layer*, *\**, *reference=None*, *do_fully_editable=False*)
    :   Create an overridden local copy of this linked data-block, and most of its dependencies when it is a Collection or and Object

        Parameters:
        :   - **scene** ([`Scene`](bpy.types.Scene.html#bpy.types.Scene "bpy.types.Scene"), (never None)) – In which scene the new overrides should be instantiated
            - **view_layer** ([`ViewLayer`](bpy.types.ViewLayer.html#bpy.types.ViewLayer "bpy.types.ViewLayer"), (never None)) – In which view layer the new overrides should be instantiated
            - **reference** ([`ID`](#bpy.types.ID "bpy.types.ID"), (optional)) – Another ID (usually an Object or Collection) used as a hint to decide where to instantiate the new overrides
            - **do_fully_editable** (*boolean**,* *(**optional**)*) – Make all library overrides generated by this call fully editable by the user (none will be ‘system overrides’)

        Returns:
        :   New overridden local copy of the root ID

        Return type:
        :   [`ID`](#bpy.types.ID "bpy.types.ID")

    user_clear()
    :   Clear the user count of a data-block so its not saved, on reload the data will be removed

        This function is for advanced use only, misuse can crash Blender since the user
        count is used to prevent data being removed when it is used.

        ```
        # This example shows what _not_ to do, and will crash Blender.
        import bpy

        # Object which is in the scene.
        obj = bpy.data.objects["Cube"]

        # Without this, removal would raise an error.
        obj.user_clear()

        # Runs without an exception but will crash on redraw.
        bpy.data.objects.remove(obj)
        ```

    user_remap(*new_id*)
    :   Replace all usage in the .blend file of this ID by new given one

        Parameters:
        :   **new_id** ([`ID`](#bpy.types.ID "bpy.types.ID"), (never None)) – New ID to use

    make_local(*\**, *clear_proxy=True*, *clear_liboverride=False*, *clear_asset_data=True*)
    :   Make this data-block local, return local one (may be a copy of the original, in case it is also indirectly used)

        Parameters:
        :   - **clear_proxy** (*boolean**,* *(**optional**)*) – Deprecated, has no effect
            - **clear_liboverride** (*boolean**,* *(**optional**)*) – Remove potential library override data from the newly made local data
            - **clear_asset_data** (*boolean**,* *(**optional**)*) – Remove potential asset metadata so the newly local data-block is not treated as asset data-block and won’t show up in asset libraries

        Returns:
        :   This ID, or the new ID if it was copied

        Return type:
        :   [`ID`](#bpy.types.ID "bpy.types.ID")

    user_of_id(*id*)
    :   Count the number of times that ID uses/references given one

        Parameters:
        :   **id** ([`ID`](#bpy.types.ID "bpy.types.ID"), (never None)) – ID to count usages

        Returns:
        :   Number of usages/references of given id by current data-block

        Return type:
        :   int in [0, inf]

    animation_data_create()
    :   Create animation data to this ID, note that not all ID types support this

        Returns:
        :   New animation data or nullptr

        Return type:
        :   [`AnimData`](bpy.types.AnimData.html#bpy.types.AnimData "bpy.types.AnimData")

    animation_data_clear()
    :   Clear animation on this ID

    update_tag(*\**, *refresh={}*)
    :   Tag the ID to update its display data, e.g. when calling `bpy.types.Scene.update`

        Parameters:
        :   **refresh** (enum set in {`'OBJECT'`, `'DATA'`, `'TIME'`}, (optional)) – Type of updates to perform

    preview_ensure()
    :   Ensure that this ID has preview data (if ID type supports it)

        Returns:
        :   The existing or created preview

        Return type:
        :   [`ImagePreview`](bpy.types.ImagePreview.html#bpy.types.ImagePreview "bpy.types.ImagePreview")

    *classmethod* bl_rna_get_subclass(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The RNA type or default when not found.

        Return type:
        :   [`bpy.types.Struct`](bpy.types.Struct.html#bpy.types.Struct "bpy.types.Struct") subclass

    *classmethod* bl_rna_get_subclass_py(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The class or default when not found.

        Return type:
        :   type