pysonfield 4.0.3

Modular, ORM based, high efficiently "JSONField" Database Engine!

Genel Bakış

Bu veritabanı yönetim kütüphanesi, tam CRUD (Oluşturma, Okuma, Güncelleme, Silme) desteğiyle yüksek performanslı, şema tabanlı JSON destekli bir veritabanı çözümü sunar. Hafif ve verimli veri işleme için tasarlanmış olup, güçlü filtreleme, doğrulama ve dönüştürme işlevleriyle yapılandırılmış veri depolama, alma ve düzenleme olanağı sağlar.

Temel Özellikler

1. JSON Tabanlı Depolama: Hafif ve insan tarafından okunabilir hale getiren JSON tabanlı bir veritabanı yapısı kullanır.
2. Şema Uygulaması: Sütun tanımlarını kullanarak sütun doğrulamasını, tür denetimini ve benzersiz kısıtlamaları destekler.
3. Gelişmiş Sorgulama: Düzenli ifadeler (RegExp sınıfı), özel tahminler ve yapılandırılmış sorgular aracılığıyla filtreleme sağlar.
4. CRUD İşlemleri: Toplu işleme, filtreleme ve sorgu tabanlı güncellemelerle CRUD işlemleri sunar.
5. Veri Doğrulama ve Bütünlük:

• unique kısıtlamalarını destekler.
• not_null zorunluluğunu sağlar.
• İsteğe bağlı tür yükseltmesiyle otomatik tür doğrulaması sağlar.

6. ResultSet Yönetimi: Pandas DataFrames, NumPy dizileri, JSON, CSV ve Markdown dahil olmak üzere çeşitli biçimlere sonuç dönüşümüne izin verir.
7. Bağlam Yönetimi: Güvenli işlem yönetimi için with ve async with ifadelerini destekler.
8. Model Tabanlı Tasarım:

• Yapılandırılmış modelleri tanımlamak için JSONField kullanır.
• Birincil anahtarların otomatik olarak artırılmasını destekler.
• Bağımlı sütun değerlerine (depends özniteliği) izin verir.

9. Hata İşleme ve Kurtarma:

• Bozuk verileri algılar ve düzeltir. - Doğrulama ve şema uygulaması için Issues sınıfını sağlar.

10. Dışa Aktarma ve İçe Aktarma:

• Kayıtları JSON, CSV, Excel, SQLite ve diğer formatlara dönüştürün.
• Dahili veri dönüştürme yardımcı programlarıyla toplu içe aktarma/dışa aktarma.

Temel Bileşenler

• CRUD: Ekleme, güncelleme, silme ve sorgu tabanlı güncellemeler gibi veritabanı işlemlerini yönetir.
• JSONField: Doğrulama, varsayılan değerler ve kısıtlamalarla yapılandırılmış veritabanı modellerini tanımlar.
• ResultSet: Filtrelenmiş ve yapılandırılmış veri alımını yönetir.
• Where: Tahminler ve regex kalıplarıyla gelişmiş filtreleme uygular.
• JSONIC: Dosya depolama, veri doğrulama ve hata işlemeyi yöneten ana veritabanı arayüzü olarak işlev görür. - Sütun: Birincil anahtarlar, kısıtlamalar ve bağımlılıklar için seçeneklerle veritabanı alanlarının yapısını tanımlar.
• Yığın: İşlemsel işlemler ve geri alma desteği sağlar.

Kullanım Örnekleri

• Hafif Veritabanı Alternatifi: Geleneksel veritabanlarının (SQL, NoSQL) aşırı olduğu küçük ölçekli uygulamalar için uygundur.
• Gömülü Veri Depolama: Harici bağımlılıklar olmadan yapılandırılmış, kalıcı depolama gerektiren Python uygulamalarında kullanılabilir.
• Veri İşleme ve Analitiği: Veri odaklı uygulamalar için yapılandırılmış sorgulama, filtreleme ve dönüştürme yetenekleri sağlar.

Özellikler

• Şema tabanlı veri doğrulama
• JSON dosya depolaması için destek
• Tür denetimi ve veri doğrulama
• Otomatik artan alanlar
• Benzersiz kısıtlamalar
• Birincil anahtar yönetimi
• Varsayılan değer işleyicileri
• Özel sütun bağımlılıkları
• Veri inceleme ve denetimi

Kurulum

pip install pysonfield

Hızlı Başlangıç

JSONIC'in nasıl kullanılacağına dair temel bir örnek:

from pysonfield import JSONField, JSONIC, Column
from pysonfield.utils import Random

@JSONField(increment_by=1)
class UserModel:
id: str = Column(depends=Random.hash, primary_key=True)
name: str = Column(not_null=True)
age: int = Column(increment=True)
email: str = Column(unique=True)

# Veritabanı bağlantısı oluştur
JSONIC(db_path="database", model=UserModel) as db:
cursor = db.cursor()

# Yeni kayıt ekle
cursor.add({
"name": "John Doe",
"email": "[e-mail]"
})

# Değişiklikleri kaydet
cursor.commit()

Şema Tanımı

JSONField Dekoratörünü Kullanma

@JSONField dekoratörü model düzeyindeki ayarları yapılandırır:

@JSONField(
increment_by=1, # Otomatik artan alanlar için adım artırma
ignore_types=False, # Tür denetimini etkinleştir/devre dışı bırak
auto_fit_columns=True # Sütunları otomatik olarak ayarla
)
class MyModel:
# Model alanları burada

Sütun Türleri

Sütunlar çeşitli özniteliklerle tanımlanabilir:

class UserModel:
id: str = Column(primary_key=True) # Birincil anahtar alanı
name: str = Column(not_null=True) # Zorunlu sütun
age: int = Column(increment=True) # Otomatik artan
email: str = Column(unique=True) # Benzersiz sütun
created: str = Column(depends=Random.date) # Oluşturulan sütun
hash: str = Column(depends=Random.hash, unique=True) # Benzersiz hash

Sütun Özellikleri

• primary_key: Alanı benzersiz ve null değil yapar
• not_null: Sütun null olamaz
• unique: Sütun benzersiz değerlere sahip olmalı
• increment: Otomatik artış alanı
• depends: Sütun değerlerini üretme işlevi
• default: Sütun için varsayılan değer

Veritabanı İşlemleri

Veritabanına Bağlanma

# JSON Dosya Depolama
with JSONIC(db_path="database", model=MyModel) as db:
# İşlemler burada

Temel İşlemler

# İmleci al
cursor = db.cursor()

# Kayıt ekle
cursor.add({
"name": "John",
"email": "[e-mail]"
})

# Değişiklikleri kaydet
cursor.commit()

# Tüm kayıtları al
all_records = db.fetch()

# Kayıtları sorgula
results = db.query({"name": "John"})

Veri Filtreleme

# Lambda'ya göre filtrele
adults = db.stack[lambda x: x["age"] >= 18]
adults = db.stack[lambda x: x.age >= 18]
adults = db.stack[lambda age, year: age > 18 and year < 2006]

# Düzenli ifadeye göre filtrele
name_filter = RegExp(r"^John", "name")
johns = db.stack[name_filter]

Veri Doğrulaması

İnceleme Veri

# Doğrulama raporu oluştur
report = db.review(save_report=False)

# Erişim sorunları
print(report.type_issues)
print(report.unique_constraint_issues)
print(report.required_field_issues)

Hata İşleme

Yaygın istisnalar:

• KeyAlreadyExists: Birincil anahtar yineleniyor
• KeyNotFound: Gerekli alanlar eksik
• NotNullViolation: Boş olmayan alanda boş değer
• NotUniqueViolation: Benzersiz alanda yinelenen değer
• TypeError: Geçersiz veri türü
• DataCorrupted: Veritabanı dosyası bozulması

En İyi Uygulamalar

1. Model tanımlarında her zaman tür ipuçları kullanın
2. Veritabanı işlemleri için bağlam yöneticilerini (with ifadesi) kullanın
3. Onayla auto_commit devre dışı bırakıldığında açıkça değişir
4. review() kullanılarak düzenli veri doğrulaması
5. İstisnaları uygun şekilde işleme

Yapılandırma Seçenekleri

JSONIC(
db_path="database", # Depolama motoru
model=MyModel, # Veri modeli
audit_fix=True, # Bozuk verileri otomatik olarak düzelt
commit_on_exit=False, # Bağlam çıkışında otomatik olarak onayla
raise_on_validation=True, # Doğrulama sırasında istisnaları yükselt
allow_promotion=False # Tür yükseltmesine izin ver
)

Katkıda Bulunma

Katkılarınız memnuniyetle karşılanır! Lütfen bir Çekme İsteği göndermekten çekinmeyin.

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - ayrıntılar için LİSANS dosyasına bakın.