tessl/pypi-o365
O365 - Microsoft Graph and Office 365 API made easy
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
contacts.mddocs/
Contacts and Address Book
Contact management with support for personal contacts, shared address books, contact folders, and contact groups with full CRUD operations.
Capabilities
Address Book Access
Access contact services for the authenticated user or other users with proper permissions.
def address_book(self, resource: str = None) -> AddressBook:
"""
Get an address book instance for contact operations.
Parameters:
- resource: user resource identifier (defaults to authenticated user)
Returns:
- AddressBook: AddressBook instance for contact operations
"""
class AddressBook:
def __init__(self, parent: Account, main_resource: str = None): ...
def get_contacts(self, limit: int = None, **filters) -> list[Contact]:
"""
Get contacts from the address book.
Parameters:
- limit: maximum number of contacts to return
- filters: OData query filters
Returns:
- list[Contact]: List of contact objects
"""
def get_contact(self, contact_id: str) -> Contact:
"""
Get a specific contact by ID.
Parameters:
- contact_id: contact identifier
Returns:
- Contact: Contact object
"""
def new_contact(self) -> Contact:
"""
Create a new contact.
Returns:
- Contact: New contact object
"""Contact Management
Create, update, and manage individual contacts with full contact information.
class Contact:
@property
def display_name(self) -> str:
"""Contact display name."""
@property
def given_name(self) -> str:
"""First name."""
@property
def surname(self) -> str:
"""Last name."""
@property
def email_addresses(self) -> list[dict]:
"""List of email addresses."""
@property
def phone_numbers(self) -> list[dict]:
"""List of phone numbers."""
@property
def addresses(self) -> list[dict]:
"""List of postal addresses."""
@property
def company_name(self) -> str:
"""Company name."""
@property
def job_title(self) -> str:
"""Job title."""
@property
def department(self) -> str:
"""Department."""
@property
def birthday(self) -> datetime:
"""Birthday."""
@property
def notes(self) -> str:
"""Personal notes about the contact."""
def save(self) -> bool:
"""Save changes to the contact."""
def delete(self) -> bool:
"""Delete this contact."""
def add_email(self, address: str, name: str = None,
address_type: str = 'work') -> bool:
"""
Add an email address to the contact.
Parameters:
- address: email address
- name: display name for the email
- address_type: 'work', 'home', or 'other'
Returns:
- bool: True if successful
"""
def add_phone(self, number: str, phone_type: str = 'work') -> bool:
"""
Add a phone number to the contact.
Parameters:
- number: phone number
- phone_type: 'work', 'home', 'mobile', or 'other'
Returns:
- bool: True if successful
"""
def add_address(self, street: str = None, city: str = None,
state: str = None, postal_code: str = None,
country: str = None, address_type: str = 'work') -> bool:
"""
Add a postal address to the contact.
Parameters:
- street: street address
- city: city name
- state: state or province
- postal_code: postal/zip code
- country: country name
- address_type: 'work', 'home', or 'other'
Returns:
- bool: True if successful
"""Contact Folders
Organize contacts into folders for better management.
def get_contact_folders(self, limit: int = None) -> list[ContactFolder]:
"""
Get contact folders.
Parameters:
- limit: maximum number of folders to return
Returns:
- list[ContactFolder]: List of contact folder objects
"""
def get_contact_folder(self, folder_id: str = None,
folder_name: str = None) -> ContactFolder:
"""
Get a specific contact folder.
Parameters:
- folder_id: folder identifier
- folder_name: folder display name
Returns:
- ContactFolder: Contact folder object
"""
def new_contact_folder(self, folder_name: str) -> ContactFolder:
"""
Create a new contact folder.
Parameters:
- folder_name: name for the new folder
Returns:
- ContactFolder: Created contact folder object
"""
class ContactFolder:
@property
def name(self) -> str:
"""Folder display name."""
@property
def total_item_count(self) -> int:
"""Total number of contacts in folder."""
def get_contacts(self, limit: int = None) -> list[Contact]:
"""Get contacts from this folder."""
def new_contact(self) -> Contact:
"""Create a new contact in this folder."""
def delete(self) -> bool:
"""Delete this folder."""Contact Search and Filtering
Search and filter contacts based on various criteria.
def search_contacts(self, search_text: str, limit: int = None) -> list[Contact]:
"""
Search for contacts.
Parameters:
- search_text: text to search for in contact fields
- limit: maximum number of results
Returns:
- list[Contact]: Matching contacts
"""
# Common filter examples for get_contacts()
# By name: display_name__contains='Smith'
# By company: company_name='Microsoft'
# By email domain: email_addresses__any(lambda x: '@company.com' in x['address'])
# Recently created: created_time__gte=datetime(2023, 1, 1)Usage Examples
Basic Contact Operations
from O365 import Account
account = Account(credentials)
address_book = account.address_book()
# Get all contacts
contacts = address_book.get_contacts()
for contact in contacts:
print(f"Name: {contact.display_name}")
print(f"Company: {contact.company_name}")
if contact.email_addresses:
print(f"Email: {contact.email_addresses[0]['address']}")
print("---")Create New Contact
# Create a new contact with full information
new_contact = address_book.new_contact()
new_contact.given_name = "John"
new_contact.surname = "Doe"
new_contact.display_name = "John Doe"
new_contact.company_name = "Acme Corporation"
new_contact.job_title = "Software Engineer"
new_contact.department = "Engineering"
# Add contact information
new_contact.add_email("john.doe@acme.com", "Work Email", "work")
new_contact.add_email("john.personal@gmail.com", "Personal Email", "home")
new_contact.add_phone("+1-555-123-4567", "work")
new_contact.add_phone("+1-555-987-6543", "mobile")
new_contact.add_address(
street="123 Business St",
city="Seattle",
state="WA",
postal_code="98101",
country="USA",
address_type="work"
)
new_contact.notes = "Met at the tech conference in 2023"
# Save the contact
if new_contact.save():
print(f"Contact created: {new_contact.display_name}")Contact Folder Management
# Create a folder for work contacts
work_folder = address_book.new_contact_folder("Work Contacts")
# Create a folder for personal contacts
personal_folder = address_book.new_contact_folder("Personal")
# Add contacts to specific folders
work_contact = work_folder.new_contact()
work_contact.display_name = "Business Partner"
work_contact.company_name = "Partner Corp"
work_contact.add_email("partner@partnercorp.com")
work_contact.save()
# Get contacts from a specific folder
work_contacts = work_folder.get_contacts()
print(f"Work contacts: {len(work_contacts)}")Search and Filter Contacts
# Search for contacts by name
johns = address_book.search_contacts("John")
# Filter contacts by company
microsoft_contacts = address_book.get_contacts(
company_name="Microsoft"
)
# Find contacts with specific email domain
gmail_contacts = []
all_contacts = address_book.get_contacts()
for contact in all_contacts:
for email in contact.email_addresses:
if "@gmail.com" in email['address']:
gmail_contacts.append(contact)
break
print(f"Found {len(gmail_contacts)} contacts with Gmail addresses")Update Existing Contact
# Find and update a contact
contact = address_book.search_contacts("John Doe")[0]
# Update job information
contact.job_title = "Senior Software Engineer"
contact.department = "Advanced Engineering"
# Add a new phone number
contact.add_phone("+1-555-111-2222", "other")
# Update notes
contact.notes += "\nPromoted to senior engineer in 2023"
# Save changes
if contact.save():
print("Contact updated successfully")Install with Tessl CLI
npx tessl i tessl/pypi-o365