Crate photokit

Expand description

§photokit

Safe Rust bindings for Apple’s Photos framework on macOS.

Status: v0.3.0 adds the Tier-1 async_api module on top of the fully audited Photos.framework surface, with executor-agnostic futures for authorization, performChanges, image requests, and live-photo editing callbacks.

§Quick start

use photokit::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let library = PHPhotoLibrary::shared()?;
    println!("status: {:?}", PHPhotoLibrary::authorization_status());

    let assets = PHAsset::fetch(&PHFetchOptions::default())?;
    println!("assets: {}", assets.len());

    if let Some(asset) = assets.first() {
        let manager = PHImageManager::shared()?;
        let request = manager.request_image_data(
            asset,
            &PHImageRequest::new(320.0, 240.0, PHImageContentMode::AspectFit),
        )?;
        let image = request.wait(10_000)?;
        println!("image bytes: {}", image.data().len());
    }

    let _ = library.fetch_asset_collections(&PHFetchOptions::default())?;
    Ok(())
}

§Async API

Enable the async feature to access non-blocking wrappers for Photos.framework completion-handler APIs:

[dependencies]
photokit = { version = "0.3", features = ["async"] }

use photokit::async_api::AsyncPHPhotoLibrary;
use photokit::PHAccessLevel;

let status = AsyncPHPhotoLibrary::request_authorization(PHAccessLevel::ReadWrite).await?;

All async types implement std::future::Future and are executor-agnostic. See async_api for the full API surface.

§Highlights

PHPhotoLibrary authorization helpers plus summary/detailed change observers, availability observers, and persistent-change history helpers.
PHAsset, PHCollection, PHAssetCollection, and PHCollectionList fetch helpers with typed subtype/source/resource wrappers.
PHChangeRequest builders for asset, album, folder, and project mutation flows.
PHImageManager / PHCachingImageManager request handles for images, image data, live photos, video requests, and caching.
PHAssetResourceManager transfer helpers for reading or writing asset resources.
PHContentEditingInput / PHContentEditingOutput plus PHLivePhotoEditingContext for non-destructive editing workflows.
PHCloudIdentifier batch lookup helpers and richer Photos-specific error metadata.

§Coverage audit

See COVERAGE.md for the framework audit, implemented rows, partial rows, and deferred macOS-unavailable or deprecated APIs.

§Examples

The crate ships with numbered examples covering every logical area:

01_photokit_smoke
02_phasset_fetch
03_phasset_collection_fetch
04_phcollection_list_fetch
05_phphoto_library_authorization
06_phimage_manager_requests
07_phfetch_result_methods
08_phchange_observer
09_phcontent_editing_input
10_phcontent_editing_output
11_phobject_change_details
12_phfetch_options_builder
13_phasset_creation_request
14_phlive_photo
15_phcloud_identifier
16_async_api (requires --features async)

Run them with:

for ex in examples/*.rs; do
  name="$(basename "$ex" .rs)"
  if [ "$name" = "16_async_api" ]; then
    cargo run --example "$name" --features async
  else
    cargo run --example "$name"
  fi
done

§Verification

cargo clippy --all-features --all-targets -- -D warnings
cargo test --all-features
for ex in examples/*.rs; do
  name="$(basename "$ex" .rs)"
  if [ "$name" = "16_async_api" ]; then
    cargo run --example "$name" --features async
  else
    cargo run --example "$name"
  fi
done

§License

Licensed under either of Apache-2.0 or MIT at your option.

Re-exports§

pub use asset::PHAsset;
pub use asset::PHAssetBurstSelectionType;
pub use asset::PHAssetEditOperation;
pub use asset::PHAssetMediaSubtype;
pub use asset::PHAssetPlaybackStyle;
pub use asset::PHAssetResource;
pub use asset::PHAssetResourceType;
pub use asset::PHAssetSourceType;
pub use asset::PHCoordinate;
pub use asset::PHMediaType;
pub use asset_change_request::PHAssetChangeRequest;
pub use asset_collection::PHAssetCollection;
pub use asset_collection::PHAssetCollectionSubtype;
pub use asset_collection::PHAssetCollectionType;
pub use asset_collection::PHCollectionEditOperation;
pub use asset_collection_change_request::PHAssetCollectionAssetMutation;
pub use asset_collection_change_request::PHAssetCollectionChangeRequest;
pub use asset_creation_request::PHAssetCreationRequest;
pub use asset_creation_request::PHAssetCreationResource;
pub use asset_creation_request::PHAssetResourceCreationOptions;
pub use asset_resource_manager::PHAssetResourceDataResult;
pub use asset_resource_manager::PHAssetResourceManager;
pub use asset_resource_manager::PHAssetResourceRequestOptions;
pub use asset_resource_manager::PHAssetResourceWriteResult;
pub use change::PHChange;
pub use change_request::PHChangeRequest;
pub use cloud_identifier::PHCloudIdentifier;
pub use cloud_identifier::PHCloudIdentifierMapping;
pub use cloud_identifier::PHLocalIdentifierMapping;
pub use collection::PHCollection;
pub use collection_list::PHCollectionList;
pub use collection_list::PHCollectionListSubtype;
pub use collection_list::PHCollectionListType;
pub use collection_list_change_request::PHCollectionListChangeRequest;
pub use collection_list_change_request::PHCollectionListChildMutation;
pub use content_editing_controller::PHContentEditingController;
pub use content_editing_controller::PHContentEditingPlaceholderImage;
pub use content_editing_input::PHAdjustmentData;
pub use content_editing_input::PHContentEditingInput;
pub use content_editing_input::PHContentEditingInputInfo;
pub use content_editing_input::PHContentEditingInputRequestOptions;
pub use content_editing_output::PHContentEditingOutput;
pub use content_editing_output::PHContentEditingOutputInfo;
pub use error::NSErrorInfo;
pub use error::PHAuthorizationStatus;
pub use error::PHLocalIdentifiersErrorKey;
pub use error::PHPhotosError;
pub use error::PHPhotosErrorDomain;
pub use error::PhotoKitError;
pub use fetch_options::PHFetchOptions;
pub use fetch_options::PHSortDescriptor;
pub use fetch_result::PHFetchResult;
pub use fetch_result_change_details::PHFetchResultChangeDetails;
pub use fetch_result_change_details::PHFetchResultMove;
pub use geometry::PHColor;
pub use geometry::PHRect;
pub use image_manager::PHCachingImageManager;
pub use image_manager::PHImageContentMode;
pub use image_manager::PHImageDataRequestHandle;
pub use image_manager::PHImageDataResult;
pub use image_manager::PHImageErrorKey;
pub use image_manager::PHImageManager;
pub use image_manager::PHImageManagerMaximumSize;
pub use image_manager::PHImageRequest;
pub use image_manager::PHImageRequestHandle;
pub use image_manager::PHImageRequestOptionsDeliveryMode;
pub use image_manager::PHImageRequestOptionsResizeMode;
pub use image_manager::PHImageRequestOptionsVersion;
pub use image_manager::PHImageResult;
pub use image_manager::PHImageResultRequestIDKey;
pub use image_manager::PHImageSize;
pub use image_manager::PHLivePhotoRequestHandle;
pub use image_manager::PHVideoRequestOptions;
pub use image_manager::PHVideoRequestOptionsDeliveryMode;
pub use image_manager::PHVideoRequestOptionsVersion;
pub use image_manager::PHVideoResult;
pub use live_photo::PHLivePhoto;
pub use live_photo::PHLivePhotoInfoErrorKey;
pub use live_photo::PHLivePhotoResult;
pub use live_photo_editing_context::PHLivePhotoEditingContext;
pub use live_photo_editing_context::PHLivePhotoEditingContextInfo;
pub use live_photo_editing_context::PHLivePhotoEditingSaveResult;
pub use live_photo_editing_context::PHLivePhotoFrame;
pub use live_photo_editing_context::PHLivePhotoFrameProcessingDecision;
pub use live_photo_editing_context::PHLivePhotoFrameType;
pub use live_photo_view::PHLivePhotoView;
pub use live_photo_view::PHLivePhotoViewContentMode;
pub use live_photo_view::PHLivePhotoViewDelegate;
pub use live_photo_view::PHLivePhotoViewDelegateEvent;
pub use live_photo_view::PHLivePhotoViewDelegateEventKind;
pub use live_photo_view::PHLivePhotoViewInfo;
pub use live_photo_view::PHLivePhotoViewPlaybackStyle;
pub use object::PHObject;
pub use object::PHObjectPlaceholder;
pub use object_change_details::PHObjectChangeDetails;
pub use persistent_change::PHObjectType;
pub use persistent_change::PHPersistentChange;
pub use persistent_change::PHPersistentChangeFetchResult;
pub use persistent_change::PHPersistentChangeToken;
pub use persistent_change::PHPersistentObjectChangeDetails;
pub use photo_library::PHAccessLevel;
pub use photo_library::PHAvailabilityObserver;
pub use photo_library::PHChangeObserver;
pub use photo_library::PHPhotoLibrary;
pub use photo_library::PHPhotoLibraryAvailabilityChange;
pub use photo_library::PHPhotoLibraryChange;
pub use picker::PHDirectionalRectEdge;
pub use picker::PHItemProviderInfo;
pub use picker::PHPickerCapabilities;
pub use picker::PHPickerConfiguration;
pub use picker::PHPickerConfigurationAssetRepresentationMode;
pub use picker::PHPickerConfigurationSelection;
pub use picker::PHPickerFilter;
pub use picker::PHPickerMode;
pub use picker::PHPickerResult;
pub use picker::PHPickerUpdateConfiguration;
pub use picker::PHPickerViewController;
pub use picker::PHPickerViewControllerDelegate;
pub use project::PHProject;
pub use project::PHProjectChangeRequest;
pub use project_extension::PHProjectExtensionContext;
pub use project_extension::PHProjectExtensionController;
pub use project_extension::PHProjectTypeDescription;
pub use project_extension::PHProjectTypeDescriptionDataSource;
pub use project_extension::PHProjectTypeDescriptionInvalidator;
pub use project_info::PHProjectAssetElement;
pub use project_info::PHProjectCreationSource;
pub use project_info::PHProjectElement;
pub use project_info::PHProjectInfo;
pub use project_info::PHProjectJournalEntryElement;
pub use project_info::PHProjectMapAnnotation;
pub use project_info::PHProjectMapElement;
pub use project_info::PHProjectRegionOfInterest;
pub use project_info::PHProjectSection;
pub use project_info::PHProjectSectionContent;
pub use project_info::PHProjectSectionElement;
pub use project_info::PHProjectSectionType;
pub use project_info::PHProjectTextElement;
pub use project_info::PHProjectTextElementType;

Modules§

asset: Wraps PHAsset, PHAssetResource, and related Photos framework asset types.
asset_change_request: Wraps PHAssetChangeRequest mutation APIs.
asset_collection: Wraps PHAssetCollection and related Photos framework collection types.
asset_collection_change_request: Wraps PHAssetCollectionChangeRequest mutation APIs.
asset_creation_request: Wraps PHAssetCreationRequest creation APIs.
asset_resource_manager: Wraps PHAssetResourceManager.
async_apiasync: Async wrappers for Photos framework completion-handler APIs. Async API for photokit (Photos.framework)
change: Wraps PHChange.
change_request: Traits for Photos framework change-request wrappers.
cloud_identifier: Wraps PHCloudIdentifier and related Photos framework identifier mappings.
collection: Wraps PHCollection.
collection_list: Wraps PHCollectionList and related Photos framework list types.
collection_list_change_request: Wraps PHCollectionListChangeRequest mutation APIs.
content_editing_controller: Wraps the PHContentEditingController protocol contract.
content_editing_input: Wraps PHContentEditingInput and related Photos framework editing-input types.
content_editing_output: Wraps PHContentEditingOutput and related Photos framework editing-output types.
error: Wraps Photos framework authorization and error values.
fetch_options: Wraps PHFetchOptions.
fetch_result: Wraps PHFetchResult.
fetch_result_change_details: Wraps PHFetchResultChangeDetails.
geometry: Shared geometry and color helper payloads used by PhotosUI wrappers.
image_manager: Wraps PHImageManager and PHCachingImageManager.
library: Re-exports Photos framework wrapper types.
live_photo: Wraps PHLivePhoto and related request results.
live_photo_editing_context: Wraps PHLivePhotoEditingContext and related frame-processing types.
live_photo_view: Wraps PHLivePhotoView and related PhotosUI playback callbacks.
object: Wraps PHObject and PHObjectPlaceholder.
object_change_details: Wraps PHObjectChangeDetails.
persistent_change: Wraps persistent change history Photos framework types.
photo_library: Wraps PHPhotoLibrary and observer registration APIs.
picker: Wraps the PHPicker family in PhotosUI.
prelude: Common imports.
project: Wraps PHProject and PHProjectChangeRequest.
project_extension: Wraps PhotosUI project-extension context and type-description helpers.
project_info: Wraps PhotosUI PHProjectInfo and related immutable project-content types.
types: Re-exports shared Photos framework wrapper types.

Crate photokit

Crate photokit Copy item path

§photokit

§Quick start

§Async API

§Highlights

§Coverage audit

§Examples

§Verification

§License

Re-exports§

Modules§

Crate photokit