> ## Documentation Index
> Fetch the complete documentation index at: https://docs.speckle.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with Speckle Objects

> Learn how to create, structure, and work with Speckle Base objects

## What You'll Learn

By the end of this guide, you'll understand:

* ✅ How to create and structure `Base` objects
* ✅ The difference between direct attributes and the properties dictionary
* ✅ How to access and discover object properties
* ✅ How to work with lists and collections

## Prerequisites

Before starting this guide, you should:

* Have [specklepy installed](/developers/sdks/python/getting-started/installation)
* Understand basic Python (classes, lists, dictionaries)
* Be familiar with the [quickstart](/developers/sdks/python/getting-started/quickstart)

<Info>
  This guide focuses on **working with objects** - not sending/receiving them. For send/receive
  operations, see the [Quickstart](/developers/sdks/python/getting-started/quickstart).
</Info>

## How do I create a Speckle object?

You need to create custom data structures or add metadata to geometry for your Speckle project. Use the `Base` class - it's the foundation of all Speckle objects and supports dynamic properties:

```python lines icon="python" theme={null}
from specklepy.objects import Base

# Create a base object
obj = Base()

# Add direct attributes
obj.name = "My Wall"
obj.elementId = "wall-001"
obj.height = 3.5
obj.isLoadBearing = True

# Add nested structure
obj.elements = []  # Will hold child objects

print(f"Created: {obj.name}")
```

`Base` objects are Python classes that accept any property name dynamically (no predefined schema needed), serialize automatically for Speckle, support nesting (objects within objects), and work with Python's native attribute access.

When to create Base objects:

* Building custom data structures (surveys, analysis results, schedules)
* Grouping related objects together
* Adding application-specific metadata

<Warning>
  **Don't use reserved names:** Avoid property names starting with `_` or matching Base methods like `id`, `speckle_type`, `get_member_names()`. These have special meanings.

  ```python theme={null}
  # ❌ Bad - overwrites internal property
  obj.id = "custom-123"  # This sets the Speckle hash ID

  # ✅ Good - use your own naming
  obj.elementId = "custom-123"
  ```
</Warning>

## How do I add metadata: direct attributes vs. properties dictionary?

You need to attach metadata to objects, but you're unsure whether to use direct attributes (`obj.name`) or the properties dictionary (`obj.properties["name"]`).

Use direct attributes for structure and organization:

```python lines icon="python" theme={null}
from specklepy.objects import Base

# Direct attributes define YOUR data structure
building = Base()
building.name = "Building A"
building.address = "123 Main St"
building.levels = []  # Your hierarchy
building.elements = []  # Your organization

# Add a level
level = Base()
level.name = "Level 1"
level.elevation = 0.0
level.elements = []  # Objects on this level
building.levels.append(level)
```

Use the properties dictionary for queryable metadata:

```python lines icon="python" theme={null}
from specklepy.objects import Base

# Properties dict for metadata that other apps should find
wall = Base()
wall.name = "W-101"

# Standard BIM metadata
wall.properties = {
    "category": "Walls",
    "material": "Concrete",
    "thickness": 200,
    "fireRating": "2 hour",
    "isLoadBearing": True,
    "cost": 1500.00
}

# Access safely with defaults
material = wall.properties.get("material", "Unknown")
thickness = wall.properties.get("thickness", 0)
```

**Direct attributes** (`obj.name`) are part of your object's structure, provide Python-level property access, and are good for relationships and hierarchies like `obj.levels`, `obj.elements`, `obj.children`.

**Properties dictionary** (`obj.properties`) is a standardized metadata container, follows BIM connector conventions, makes data searchable across applications, and commonly uses keys like `category`, `family`, `type`, `material`.

<Info>
  **Which to use?** Both are valid Speckle patterns! The `properties` dictionary is a *convention*
  that makes metadata more discoverable. If Revit sends a wall, its category will be in
  `properties["category"]` - following this pattern makes your data easier to work with across
  platforms.
</Info>

Combining both approaches:

```python lines icon="python" theme={null}
from specklepy.objects import Base
from specklepy.objects.geometry import Point, Mesh

# Create a beam with both structure and metadata
beam = Base()

# Direct attributes - your structure
beam.name = "B-205"
beam.startPoint = Point(x=0, y=0, z=3.5)
beam.endPoint = Point(x=5, y=0, z=3.5)
beam.displayValue = mesh  # Geometry reference

# Properties dict - queryable metadata
beam.properties = {
    "category": "Structural Framing",
    "family": "Steel Beam",
    "type": "W12x26",
    "material": "Steel",
    "length": 5.0,
    "weight": 130.0
}
```

## How do I access object properties?

You have a Speckle object and need to read its properties, but you don't know what properties it has or how to access them safely.

For direct attributes:

```python lines icon="python" theme={null}
# Direct access (if you know the property exists)
name = obj.name
height = obj.height

# Safe access with hasattr()
if hasattr(obj, "name"):
    print(f"Name: {obj.name}")
else:
    print("No name property")

# Safe access with getattr() and default
name = getattr(obj, "name", "Unnamed")
height = getattr(obj, "height", 0.0)
```

For properties dictionary:

```python lines icon="python" theme={null}
# Direct access (might raise KeyError)
category = obj.properties["category"]  # KeyError if missing!

# ✅ Safe access with .get() and default
category = obj.properties.get("category", "Unknown")
material = obj.properties.get("material", "Not specified")

# Check if key exists
if "category" in obj.properties:
    print(f"Category: {obj.properties['category']}")
```

**Discovering all properties** - use `get_member_names()` to discover what properties an object has:

```python lines icon="python" theme={null}
from specklepy.objects import Base

obj = Base()
obj.name = "Widget"
obj.value = 42
obj.tags = ["important", "new"]

# Get all property names
property_names = obj.get_member_names()
print(property_names)
# ['name', 'value', 'tags', 'id', 'speckle_type', ...]

# Loop through all properties
for prop_name in obj.get_member_names():
    value = getattr(obj, prop_name, None)
    print(f"{prop_name}: {value}")
```

<Accordion title="What does get_member_names() return?">
  `get_member_names()` returns all property names on the object, **automatically filtering out**:

  * Private members (starting with `_`)
  * Methods and functions
  * Class attributes

  This means you get a clean list of just the data properties. No need to check `if not name.startswith("_")` - it's already filtered!

  ```python theme={null}
  # get_member_names() already excludes private members
  for name in obj.get_member_names():
      value = getattr(obj, name, None)  # Clean, no filtering needed
  ```
</Accordion>

Safe property access pattern:

```python lines icon="python" expandable theme={null}
def safely_read_object(obj):
    """Read all properties from an object safely."""

    # Read known direct attributes with defaults
    name = getattr(obj, "name", "Unnamed")

    # Read properties dictionary safely
    properties = {}
    if hasattr(obj, "properties") and obj.properties:
        category = obj.properties.get("category", "Unknown")
        material = obj.properties.get("material", "Not specified")
        properties = {
            "category": category,
            "material": material
        }

    return {
        "name": name,
        "properties": properties
    }

# Use it
info = safely_read_object(wall)
print(f"Wall: {info['name']}, Category: {info['properties']['category']}")
```

<Warning>
  **Don't assume properties exist!** Speckle objects can come from different sources with different schemas. Always use safe access patterns:

  ```python theme={null}
  # ❌ Bad - will crash if property doesn't exist
  category = obj.properties["category"]
  name = obj.name

  # ✅ Good - handles missing properties gracefully
  category = obj.properties.get("category", "Unknown")
  name = getattr(obj, "name", "Unnamed")
  ```
</Warning>

## How do I work with lists and collections?

You need to work with multiple objects - filtering them, counting them, or processing them in bulk.

Looping through lists:

```python lines icon="python" theme={null}
from specklepy.objects import Base

# Create a collection of objects
building = Base()
building.elements = []

for i in range(5):
    element = Base()
    element.name = f"Element-{i}"
    element.properties = {"category": "Walls" if i % 2 == 0 else "Floors"}
    building.elements.append(element)

# Loop through elements
for element in building.elements:
    name = getattr(element, "name", "unnamed")
    category = element.properties.get("category", "Unknown")
    print(f"{name}: {category}")
```

Filtering lists:

```python lines icon="python" theme={null}
# Filter with list comprehension
walls = [
    obj for obj in building.elements
    if obj.properties.get("category") == "Walls"
]

print(f"Found {len(walls)} walls")

# Filter with multiple criteria
load_bearing_walls = [
    obj for obj in building.elements
    if obj.properties.get("category") == "Walls"
    and obj.properties.get("isLoadBearing", False)
]
```

Counting and aggregating:

```python lines icon="python" theme={null}
# Count by category
from collections import Counter

categories = Counter(
    obj.properties.get("category", "Unknown")
    for obj in building.elements
)

print(categories)
# Counter({'Walls': 3, 'Floors': 2})

# Sum numeric properties
total_area = sum(
    obj.properties.get("area", 0.0)
    for obj in building.elements
)

print(f"Total area: {total_area}")
```

**Working with nested collections** - many Speckle objects use `elements` arrays for hierarchical structures:

<Note>
  **Terminology Note:** Examples here use terms like "building", "level", "room" to illustrate
  hierarchical concepts. Real BIM data from connectors (Revit, Rhino, etc.) uses **proxy
  structures** rather than direct nesting - for example, Revit levels are `LevelProxy` objects that
  reference elements by ID. See [Proxification](/developers/sdks/python/concepts/proxification) and
  [BIM Data Patterns](/developers/sdks/python/guides/bim-data-patterns) for actual BIM structures.
</Note>

```python lines icon="python" expandable theme={null}
from specklepy.objects import Base

# Create hierarchical structure (illustrative example)
building = Base()
building.name = "Building A"
building.elements = []

# Add levels
for level_num in range(3):
    level = Base()
    level.name = f"Level {level_num}"
    level.properties = {"category": "Levels", "elevation": level_num * 3.5}
    level.elements = []  # Objects on this level

    # Add rooms to this level
    for room_num in range(4):
        room = Base()
        room.name = f"Room {level_num}{room_num}"
        room.properties = {"category": "Rooms", "area": 25.0}
        level.elements.append(room)

    building.elements.append(level)

# Process hierarchy
for level in building.elements:
    level_name = getattr(level, "name", "unnamed")
    room_count = len(level.elements) if hasattr(level, "elements") else 0
    print(f"{level_name}: {room_count} rooms")
```

Common collection patterns:

```python lines icon="python" theme={null}
# Check if object has elements
if hasattr(obj, "elements") and obj.elements:
    print(f"Object has {len(obj.elements)} elements")
    for element in obj.elements:
        process(element)

# Safe iteration (handles missing elements)
elements = getattr(obj, "elements", [])
for element in elements:
    process(element)

# Find first match
def find_first(objects, category):
    """Find first object with matching category."""
    for obj in objects:
        if obj.properties.get("category") == category:
            return obj
    return None

wall = find_first(building.elements, "Walls")
```

<Warning>
  Check if elements exists before looping:

  ```python theme={null}
  # ❌ Bad - crashes if no elements property
  for element in obj.elements:
      process(element)

  # ✅ Good - safe check first

  if hasattr(obj, "elements"):
  for element in obj.elements:
  process(element)

  # ✅ Also good - use getattr with default

  for element in getattr(obj, "elements", []):
  process(element)

  ```
</Warning>

## Practical Examples

### Example 1: Create a Survey Point Collection

```python lines icon="python" expandable theme={null}
from specklepy.objects import Base
from specklepy.objects.geometry import Point

# Create survey collection
survey = Base()
survey.name = "Site Survey 2024-01"
survey.date = "2024-01-15"
survey.surveyor = "Jane Smith"
survey.points = []

# Add survey points
coordinates = [
    (0, 0, 100.5),
    (10, 0, 100.8),
    (10, 10, 101.2),
    (0, 10, 100.9)
]

for i, (x, y, z) in enumerate(coordinates):
    point = Point(x=x, y=y, z=z)
    point.units = "m"

    # Add metadata as properties
    point.properties = {
        "pointId": f"SP-{i+1:03d}",
        "accuracy": 0.01,
        "method": "GPS"
    }

    survey.points.append(point)

print(f"Survey '{survey.name}' has {len(survey.points)} points")
```

## Example 2: Filter and Summarize Objects

```python lines icon="python" expandable theme={null}
from collections import Counter

def filter_by_property(objects, key, value):
    """Filter objects by property key-value pair."""
    return [
        obj for obj in objects
        if obj.properties.get(key) == value
    ]

def summarize_objects(objects):
    """Create summary statistics for objects."""

    if not objects:
        return "No objects to summarize"

    # Count by category
    categories = Counter(
        obj.properties.get("category", "Unknown")
        for obj in objects
    )

    # Calculate total area (if present)
    total_area = sum(
        obj.properties.get("area", 0.0)
        for obj in objects
    )

    return {
        "count": len(objects),
        "categories": dict(categories),
        "total_area": total_area
    }

# Use the functions
elements = building.elements
walls = filter_by_property(elements, "category", "Walls")
summary = summarize_objects(walls)

print(f"Found {summary['count']} walls")
print(f"Categories: {summary['categories']}")
print(f"Total area: {summary['total_area']} m²")
```

### Example 3: Build a Hierarchy

```python lines icon="python" expandable theme={null}
from specklepy.objects import Base

def create_project_hierarchy():
    """Create a multi-level project hierarchy."""

    # Project root
    project = Base()
    project.name = "Office Building"
    project.elements = []

    # Building
    building = Base()
    building.name = "Building A"
    building.properties = {"type": "Office", "floors": 3}
    building.elements = []

    # Add levels
    for floor in range(3):
        level = Base()
        level.name = f"Level {floor + 1}"
        level.properties = {
            "category": "Levels",
            "elevation": floor * 3.5,
            "area": 1000.0
        }
        level.elements = []

        # Add spaces
        for space in range(5):
            room = Base()
            room.name = f"Room {floor + 1}.{space + 1}"
            room.properties = {
                "category": "Rooms",
                "area": 25.0,
                "occupancy": 4
            }
            level.elements.append(room)

        building.elements.append(level)

    project.elements.append(building)
    return project

# Create and inspect
project = create_project_hierarchy()
building = project.elements[0]

for level in building.elements:
    level_name = level.name
    room_count = len(level.elements)
    print(f"{level_name}: {room_count} rooms")
```

## Learn More

Core Concepts:

* [Objects & Base Class](/developers/sdks/python/concepts/objects) - Deep dive into Base and object system
* [Data Types](/developers/sdks/python/concepts/data-types) - Understanding Speckle's type system

Guides:

* [Simple Data Patterns](/developers/sdks/python/guides/simple-data-patterns) - More examples of custom data structures
* [Intermediate: Finding and Extracting Data](/developers/sdks/python/guides/how-to-find-and-extract-data) - Learn to traverse and filter nested structures

API Reference:

* [Base class methods](/developers/sdks/python/api-reference/operations) - Complete Base API documentation

## Next Steps

Now that you understand how to work with Speckle objects, you're ready to:

1. **Learn traversal** - Navigate nested object structures recursively
2. **Extract data** - Filter and find specific objects in complex hierarchies
3. **Work with geometry** - Extract and manipulate displayValue meshes from BIM objects

Continue to [Intermediate: Finding and Extracting Data](/developers/sdks/python/guides/how-to-find-and-extract-data) →